// SPDX-FileCopyrightText: 2026 Jeffrey C. Ollie // 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); }