Something went wrong. Try again.
Sender Policy Framework (RFC 7208) for Zig: the record grammar, the macro language, and an evaluator that takes its resolver from you.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579// SPDX-FileCopyrightText: 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! The macro language of [RFC 7208//! §7](https://datatracker.ietf.org/doc/html/rfc7208#section-7).//!//! Almost every place an SPF record names a domain, it may instead name a//! *pattern* — `exists:%{ir}.%{l1r+}._spf.%{d}` is a real thing people//! publish — and the pattern is expanded with the sender, the client//! address and the domain under evaluation before the name is looked up.//! It is a small language, and it is where a surprising amount of the//! conformance suite lives.//!//! Nothing here does I/O. Every value a macro can expand to is handed in//! through `Context`, including `%{p}`, which is a reverse lookup the//! caller must have already done — the same division as everywhere else//! in this library, and what lets the whole of RFC 7208's test suite run//! against a table of records with no network at all.
const std = @import("std");const z46 = @import("z46");
/// The longest a domain name may be, and so the largest buffer an/// expansion used as one can need. §7.3 truncates to fit rather than/// failing.pub const max_domain_len = 253;
pub const Error = error{ /// The string is not a well-formed macro-string: an unknown macro /// letter, a missing `}`, a zero repeat count, a byte outside the /// visible ASCII a macro-literal allows. InvalidMacro, /// A `%{c}`, `%{r}` or `%{t}` outside an `exp=` explanation, where /// §7.2 does not allow them. MacroNotAllowedHere, /// The expansion did not fit the buffer it was given. A domain-spec /// cannot raise this — it is truncated instead — so this is only /// reachable from explanation text. NoSpace,};
/// The macro letters of §7.2. The three at the end are allowed only in an/// explanation, which is what `Options.explanation` decides.pub const Letter = enum { /// The sender, `local-part@domain`. sender, /// The local part of the sender. local_part, /// The domain of the sender. sender_domain, /// The domain currently being evaluated, which is not the sender's /// domain once an `include:` or `redirect=` has been followed. domain, /// The client address: a dotted quad, or for IPv6 the 32 nibbles /// separated by dots, which is the form a reverse lookup uses. ip, /// The validated domain name of the client, or `unknown`. Deprecated /// by §7.2 for the same reason the `ptr` mechanism is: it costs a /// lookup that usually answers nothing. validated_domain, /// The HELO/EHLO domain. helo, /// `in-addr` or `ip6`, which is the label that goes between an /// address and `.arpa`. ip_version, /// The client address in its ordinary readable form. client_ip, /// The domain name of the host doing the checking. receiver, /// The current time, in seconds since the epoch. timestamp,
fn parse(byte: u8) ?Letter { return switch (std.ascii.toLower(byte)) { 's' => .sender, 'l' => .local_part, 'o' => .sender_domain, 'd' => .domain, 'i' => .ip, 'p' => .validated_domain, 'h' => .helo, 'v' => .ip_version, 'c' => .client_ip, 'r' => .receiver, 't' => .timestamp, else => null, }; }
/// §7.2: `c`, `r` and `t` are allowed only in explanation text. pub fn explanationOnly(letter: Letter) bool { return switch (letter) { .client_ip, .receiver, .timestamp => true, else => false, }; }};
/// What a macro-string may refer to. `explanation` is false everywhere a/// domain is being named and true only inside the TXT record an `exp=`/// points at.pub const Options = struct { explanation: bool = false,};
/// The sender, kept in halves because `%{s}`, `%{l}` and `%{o}` want/// different parts of it and a HELO check has no local part of its own.pub const Sender = struct { /// §2.4: a MAIL FROM with an empty reverse-path is checked as /// `postmaster` at the HELO domain, so this is never empty. local_part: []const u8, domain: []const u8,};
/// Everything a macro can expand to. The caller assembles it; nothing/// here goes looking.pub const Context = struct { /// `%{s}`, `%{l}`, `%{o}`. sender: Sender, /// `%{d}` — the domain being evaluated right now, which changes as /// `include:` and `redirect=` are followed. domain: []const u8, /// `%{i}`, `%{v}`, `%{c}`. client_ip: z46.Address, /// `%{h}`. helo: []const u8, /// `%{p}`. Null expands to `unknown`, which is what §7.2 asks for /// when there is no validated name — and what a caller that declines /// to do the lookup at all should leave it as. validated_domain: ?[]const u8 = null, /// `%{r}`, explanation only. receiver: []const u8 = "unknown", /// `%{t}`, explanation only: seconds since the epoch. timestamp: i64 = 0,};
/// One `%{...}` and what it asks for.const Expansion = struct { letter: Letter, /// §7.3: an uppercase letter expands the same and is then URL-escaped. escape: bool, /// How many parts to keep from the right, or null for all of them. keep: ?u32, /// Whether to reverse the parts before keeping any. reverse: bool, /// The characters the value is split on. `.` when none were given. delimiters: []const u8, /// How many bytes of input this occupied, `%{` and `}` included. len: usize,};
/// Parses one macro-expand, which the caller has established begins with/// `%`. The two-character forms (`%%`, `%_`, `%-`) are handled by the/// caller, since they expand to a literal rather than to a value.fn parseExpansion(text: []const u8, options: Options) Error!Expansion { std.debug.assert(text[0] == '%'); if (text.len < 4 or text[1] != '{') return error.InvalidMacro;
const letter = Letter.parse(text[2]) orelse return error.InvalidMacro; if (letter.explanationOnly() and !options.explanation) { return error.MacroNotAllowedHere; }
var index: usize = 3; var keep: ?u32 = null; while (index < text.len and std.ascii.isDigit(text[index])) : (index += 1) { // A count larger than the number of parts means "all of them", so // saturating is the same answer as a wider integer would give and // cannot overflow on a record that names a preposterous one. const digit = text[index] - '0'; keep = (keep orelse 0) *| 10 +| digit; } // §7.1: "If a DIGIT is specified, the value MUST be nonzero." if (keep) |count| { if (count == 0) return error.InvalidMacro; }
var reverse = false; if (index < text.len and std.ascii.toLower(text[index]) == 'r') { reverse = true; index += 1; }
const delimiters_start = index; while (index < text.len and isDelimiter(text[index])) : (index += 1) {} const delimiters = if (index == delimiters_start) "." else text[delimiters_start..index];
if (index >= text.len or text[index] != '}') return error.InvalidMacro; return .{ .letter = letter, .escape = std.ascii.isUpper(text[2]), .keep = keep, .reverse = reverse, .delimiters = delimiters, .len = index + 1, };}
fn isDelimiter(byte: u8) bool { return switch (byte) { '.', '-', '+', ',', '/', '_', '=' => true, else => false, };}
/// A macro-literal is any visible ASCII character except `%`, which is/// `%x21-24 / %x26-7E`. A control character or anything with the high bit/// set is a syntax error rather than something to pass through.////// A space is the exception, and only in an explanation: §6.2's/// `explain-string` is `*( macro-string / SP )`, because an explanation is/// a sentence for a human and a record's terms are separated by spaces.fn isLiteral(byte: u8, options: Options) bool { return switch (byte) { 0x21...0x24, 0x26...0x7e => true, ' ' => options.explanation, else => false, };}
/// Checks that a macro-string is well formed, without needing anything to/// expand it with. This is what the record parser calls: a record with a/// malformed macro in it is a syntax error, and §4.6 wants syntax errors/// found before any of the record is evaluated rather than when a/// mechanism happens to be reached.pub fn validate(text: []const u8, options: Options) Error!void { var index: usize = 0; while (index < text.len) { if (text[index] == '%') { if (index + 1 >= text.len) return error.InvalidMacro; switch (text[index + 1]) { '%', '_', '-' => index += 2, '{' => index += (try parseExpansion(text[index..], options)).len, else => return error.InvalidMacro, } } else { if (!isLiteral(text[index], options)) return error.InvalidMacro; index += 1; } }}
/// Expands a macro-string into `buffer`.////// `truncate` is what §7.3 asks for when the result is used as a domain/// name: a name longer than 253 characters has whole labels removed from/// the left until it fits, rather than being rejected. Explanation text/// passes false and gets `error.NoSpace` instead, since there is nothing/// sensible to drop.pub fn expand( buffer: []u8, text: []const u8, context: Context, options: Options, truncate: bool,) Error![]const u8 { var out: usize = 0; var index: usize = 0; while (index < text.len) { if (text[index] == '%') { if (index + 1 >= text.len) return error.InvalidMacro; switch (text[index + 1]) { // §7.3's three literal escapes. `%_` is a space and `%-` // is the `%20` that a space becomes in a URL, which is // how an explanation ends up readable in a browser. '%' => { out += try put(buffer, out, "%"); index += 2; }, '_' => { out += try put(buffer, out, " "); index += 2; }, '-' => { out += try put(buffer, out, "%20"); index += 2; }, '{' => { const expansion = try parseExpansion(text[index..], options); out += try expandOne(buffer[out..], expansion, context); index += expansion.len; }, else => return error.InvalidMacro, } } else { if (!isLiteral(text[index], options)) return error.InvalidMacro; out += try put(buffer, out, text[index .. index + 1]); index += 1; } }
if (truncate and out > max_domain_len) return truncateName(buffer[0..out]); return buffer[0..out];}
fn put(buffer: []u8, at: usize, bytes: []const u8) Error!usize { if (at + bytes.len > buffer.len) return error.NoSpace; @memcpy(buffer[at..][0..bytes.len], bytes); return bytes.len;}
/// §7.3: "the left side is truncated to fit, by removing successive/// domain labels from the left until the total length is 253 or less."fn truncateName(name: []const u8) []const u8 { var rest = name; while (rest.len > max_domain_len) { const dot = std.mem.indexOfScalar(u8, rest, '.') orelse return rest[rest.len - max_domain_len ..]; rest = rest[dot + 1 ..]; } return rest;}
/// The value a single macro expands to, transformed and escaped.fn expandOne(buffer: []u8, expansion: Expansion, context: Context) Error!usize { // Every macro value is bounded: an address, a domain name, a local // part, a timestamp. The largest is a sender, which is a local part // and a domain and an `@`. var value_buf: [max_domain_len * 2 + 1]u8 = undefined; const value = try macroValue(&value_buf, expansion.letter, context);
// Split, reverse and keep. The parts are rejoined with "." whatever // they were split on, which is the point of the delimiter list: it // says how to take a value apart, not how to put it back together. var parts: [max_domain_len]([]const u8) = undefined; var count: usize = 0; var rest = value; while (count < parts.len) { const at = std.mem.indexOfAny(u8, rest, expansion.delimiters) orelse { parts[count] = rest; count += 1; break; }; parts[count] = rest[0..at]; count += 1; rest = rest[at + 1 ..]; } var kept = parts[0..count];
if (expansion.reverse) std.mem.reverse([]const u8, kept); if (expansion.keep) |keep| { if (keep < kept.len) kept = kept[kept.len - keep ..]; }
var out: usize = 0; for (kept, 0..) |part, i| { if (i > 0) out += try put(buffer, out, "."); if (expansion.escape) { out += try escape(buffer[out..], part); } else { out += try put(buffer, out, part); } } return out;}
/// §7.3: an uppercase macro is URL-escaped, keeping RFC 3986's unreserved/// set and percent-encoding everything else.fn escape(buffer: []u8, text: []const u8) Error!usize { var out: usize = 0; for (text) |byte| { if (std.ascii.isAlphanumeric(byte) or byte == '-' or byte == '.' or byte == '_' or byte == '~') { out += try put(buffer, out, &.{byte}); } else { if (out + 3 > buffer.len) return error.NoSpace; _ = std.fmt.bufPrint(buffer[out..][0..3], "%{X:0>2}", .{byte}) catch unreachable; out += 3; } } return out;}
fn macroValue(buffer: []u8, letter: Letter, context: Context) Error![]const u8 { return switch (letter) { .sender => std.fmt.bufPrint(buffer, "{s}@{s}", .{ context.sender.local_part, context.sender.domain, }) catch return error.NoSpace, .local_part => context.sender.local_part, .sender_domain => context.sender.domain, .domain => context.domain, .helo => context.helo, .validated_domain => context.validated_domain orelse "unknown", .receiver => context.receiver, .ip => switch (context.client_ip) { .ipv4 => |ipv4| ipv4.bufPrint(buffer) catch return error.NoSpace, // §7.3: an IPv6 address becomes its 32 nibbles, dot // separated — the same shape as an `ip6.arpa` name, which is // what makes `%{ir}` useful. The reversing is `r`'s job, so // what is wanted here is the nibbles the right way round. .ipv6 => |ipv6| ipv6.nibbles(buffer) catch return error.NoSpace, }, // The readable form, which for IPv6 means RFC 5952: lowercase, // no leading zeros, the longest run of zero groups compressed. .client_ip => context.client_ip.bufPrint(buffer) catch return error.NoSpace, .ip_version => switch (context.client_ip) { .ipv4 => "in-addr", .ipv6 => "ip6", }, .timestamp => std.fmt.bufPrint(buffer, "{d}", .{context.timestamp}) catch return error.NoSpace, };}
const testing = std.testing;
/// The worked example of §7.4, which is the whole of the macro language/// on one page and therefore the test worth having first.const example: Context = .{ .sender = .{ .local_part = "strong-bad", .domain = "email.example.com" }, .domain = "email.example.com", .client_ip = .{ .ipv4 = .init(192, 0, 2, 3) }, .helo = "email.example.com",};
fn expectExpansion(expected: []const u8, text: []const u8, context: Context) !void { var buffer: [512]u8 = undefined; try testing.expectEqualStrings( expected, try expand(&buffer, text, context, .{}, false), );}
fn expectExplanation(expected: []const u8, text: []const u8, context: Context) !void { var buffer: [512]u8 = undefined; try testing.expectEqualStrings( expected, try expand(&buffer, text, context, .{ .explanation = true }, false), );}
test "the macro table of RFC 7208 section 7.4" { try expectExpansion("strong-bad@email.example.com", "%{s}", example); try expectExpansion("email.example.com", "%{o}", example); try expectExpansion("email.example.com", "%{d}", example); try expectExpansion("email.example.com", "%{d4}", example); try expectExpansion("email.example.com", "%{d3}", example); try expectExpansion("example.com", "%{d2}", example); try expectExpansion("com", "%{d1}", example); try expectExpansion("com.example.email", "%{dr}", example); try expectExpansion("example.email", "%{d2r}", example); try expectExpansion("strong-bad", "%{l}", example); try expectExpansion("strong.bad", "%{l-}", example); try expectExpansion("strong-bad", "%{lr}", example); try expectExpansion("bad.strong", "%{lr-}", example); try expectExpansion("strong", "%{l1r-}", example);}
test "the worked domain-spec examples of RFC 7208 section 7.4" { try expectExpansion( "3.2.0.192.in-addr._spf.example.com", "%{ir}.%{v}._spf.%{d2}", example, ); try expectExpansion( "bad.strong.lp._spf.example.com", "%{lr-}.lp._spf.%{d2}", example, ); try expectExpansion( "bad.strong.lp.3.2.0.192.in-addr._spf.example.com", "%{lr-}.lp.%{ir}.%{v}._spf.%{d2}", example, ); try expectExpansion( "3.2.0.192.in-addr.strong.lp._spf.example.com", "%{ir}.%{v}.%{l1r-}.lp._spf.%{d2}", example, ); try expectExpansion( "example.com.trusted-domains.example.net", "%{d2}.trusted-domains.example.net", example, );}
test "an IPv6 client expands to nibbles and ip6" { var context = example; context.client_ip = .{ .ipv6 = try .parse("2001:db8::cb01") }; // Straight from §7.4: the address reversed, nibble by nibble, which // is exactly the name an `ip6.arpa` lookup uses. try expectExpansion( "1.0.b.c.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6._spf.example.com", "%{ir}.%{v}._spf.%{d2}", context, ); // And `%{c}`, which is the readable form rather than the queryable // one — the distinction the two macros exist for. It is explanation // text because that is the only place §7.2 allows `%{c}`. try expectExplanation("2001:db8::cb01", "%{c}", context);}
test "the literal escapes" { // %_ is a space and %- is the %20 a space becomes in a URL, which is // why an explanation can be pasted into a browser. try expectExpansion("a%b", "a%%b", example); try expectExpansion("a b", "a%_b", example); try expectExpansion("a%20b", "a%-b", example);}
test "an uppercase macro is URL-escaped after it is transformed" { var context = example; context.sender = .{ .local_part = "strong bad+x", .domain = "example.com" }; try expectExpansion("strong%20bad%2Bx", "%{L}", context); // The escaping happens to the result, so a delimiter that was split // on is gone before there is anything to escape. try expectExpansion("x.strong%20bad", "%{Lr+}", context);}
test "a missing validated domain is the string unknown" { try expectExpansion("unknown", "%{p}", example); var context = example; context.validated_domain = "mail.example.com"; try expectExpansion("mail.example.com", "%{p}", context);}
test "explanation-only macros are refused in a domain-spec" { try testing.expectError(error.MacroNotAllowedHere, validate("%{c}", .{})); try testing.expectError(error.MacroNotAllowedHere, validate("%{r}", .{})); try testing.expectError(error.MacroNotAllowedHere, validate("%{t}", .{})); // And allowed in one. try validate("%{c} %{r} %{t}", .{ .explanation = true });}
test "malformed macros are syntax errors" { // An unknown letter, a missing brace, a stray percent. try testing.expectError(error.InvalidMacro, validate("%{z}", .{})); try testing.expectError(error.InvalidMacro, validate("%{s", .{})); try testing.expectError(error.InvalidMacro, validate("%", .{})); try testing.expectError(error.InvalidMacro, validate("%s", .{})); try testing.expectError(error.InvalidMacro, validate("%{}", .{})); // §7.1 forbids a zero repeat count, which would otherwise mean // "keep no parts at all" and expand to nothing. try testing.expectError(error.InvalidMacro, validate("%{d0}", .{})); try testing.expectError(error.InvalidMacro, validate("%{d0r}", .{})); // A macro-literal is visible ASCII only: a space ends the term in a // record, so one inside a macro-string is a syntax error rather than // a character to carry along. try testing.expectError(error.InvalidMacro, validate("a b", .{})); try testing.expectError(error.InvalidMacro, validate("a\tb", .{})); try testing.expectError(error.InvalidMacro, validate("caf\xc3\xa9", .{}));}
test "a transformer count that no record could mean is still a number" { // Saturating rather than overflowing: a count past the number of // parts means all of them, so a preposterous one is not an error. try validate("%{d999999999999999999999}", .{}); try expectExpansion("email.example.com", "%{d999999999999999999999}", example);}
/// `s` written `n` times over, in place of the `**` operator Zig 0.17/// removed.fn repeat(comptime s: []const u8, comptime n: usize) *const [s.len * n]u8 { comptime { var out: [s.len * n]u8 = undefined; for (0..n) |i| @memcpy(out[i * s.len ..][0..s.len], s); const final = out; return &final; }}
test "an expansion too long for a domain name loses labels from the left" { var context = example; // 30 labels of eight characters is 269 bytes, so the left is dropped // until it fits, and what is dropped is whole labels. const long = comptime repeat("abcdefgh.", 29) ++ "abcdefgh"; context.domain = long; var buffer: [512]u8 = undefined; const got = try expand(&buffer, "%{d}", context, .{}, true); try testing.expect(got.len <= max_domain_len); try testing.expect(std.mem.endsWith(u8, long, got)); // Whole labels: what is left starts at a label boundary. try testing.expect(long[long.len - got.len - 1] == '.'); // And without truncation the same expansion is returned whole. const whole = try expand(&buffer, "%{d}", context, .{}, false); try testing.expectEqual(long.len, whole.len);}