An SMTP client and server library for Zig implementing RFC 5321.
1// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>
2// SPDX-License-Identifier: MIT
3
4//! Shared SMTP protocol primitives ([RFC 5321](https://datatracker.ietf.org/doc/html/rfc5321)):
5//! line reading, reply parsing,
6//! command parsing, and message data dot-stuffing. Used by both the client
7//! and server layers, and usable directly for custom protocol handling.
8
9const std = @import("std");
10const Io = std.Io;
11
12pub const crlf = "\r\n";
13
14/// Bytes that may never appear in a command argument.
15///
16/// CR and LF end the command line, so a value carrying either one lets
17/// whatever follows it be read by the server as further SMTP commands — an
18/// address of `a@b>\r\nRCPT TO:<victim@c` turns one recipient into two.
19/// NUL is here because it separates the three fields of an SASL PLAIN
20/// response, where a value carrying one silently shifts the boundary
21/// between authorization identity, username and password.
22pub const forbidden_in_argument = "\r\n\x00";
23
24/// Whether `text` is safe to write into a command line as an argument.
25///
26/// This is a framing check, not address validation: it says that `text`
27/// cannot end the line early, not that it is a well-formed mailbox. The
28/// full RFC 5321 path grammar is deliberately not enforced, because plenty
29/// of addresses in real use do not satisfy it and a client that refused to
30/// carry them would be the wrong tool. Callers building commands from
31/// untrusted input should check here and reject what fails.
32pub fn isSafeArgument(text: []const u8) bool {
33 return std.mem.findAny(u8, text, forbidden_in_argument) == null;
34}
35
36test isSafeArgument {
37 try std.testing.expect(isSafeArgument("alice@example.com"));
38 try std.testing.expect(isSafeArgument("\"odd name\"@example.com"));
39 try std.testing.expect(!isSafeArgument("a@b>\r\nRCPT TO:<victim@c"));
40 try std.testing.expect(!isSafeArgument("a@b\nMAIL FROM:<c@d>"));
41 try std.testing.expect(!isSafeArgument("alice\x00root"));
42}
43
44pub const ReadLineError = error{
45 ReadFailed,
46 EndOfStream,
47 /// The line did not fit in the reader's buffer.
48 LineTooLong,
49};
50
51/// Reads one CRLF- (or bare LF-) terminated line, returning it without the
52/// line ending. The returned slice points into the reader's buffer and is
53/// invalidated by the next read.
54pub fn readLine(reader: *Io.Reader) ReadLineError![]u8 {
55 const line = reader.takeSentinel('\n') catch |err| switch (err) {
56 error.StreamTooLong => return error.LineTooLong,
57 error.ReadFailed, error.EndOfStream => |e| return e,
58 };
59 if (line.len > 0 and line[line.len - 1] == '\r') return line[0 .. line.len - 1];
60 return line;
61}
62
63/// A server reply: a 3-digit code and one or more lines of text.
64pub const Reply = struct {
65 code: u16,
66 /// Text of all reply lines joined with '\n', with codes and separators
67 /// stripped. Points into the buffer passed to `read`.
68 text: []const u8,
69
70 pub const ReadError = ReadLineError || error{
71 InvalidReply,
72 /// The reply text did not fit in the provided buffer.
73 ReplyTooLong,
74 };
75
76 /// Reads one (possibly multiline) reply. The text is copied into `buffer`
77 /// and the returned reply's `text` field points into it.
78 pub fn read(reader: *Io.Reader, buffer: []u8) ReadError!Reply {
79 var text: Io.Writer = .fixed(buffer);
80 var code: ?u16 = null;
81 var first = true;
82 while (true) {
83 const line = try readLine(reader);
84 if (line.len < 3) return error.InvalidReply;
85 const line_code = std.fmt.parseInt(u16, line[0..3], 10) catch
86 return error.InvalidReply;
87 if (line_code < 100 or line_code > 599) return error.InvalidReply;
88 if (code) |prev| {
89 // All lines of a multiline reply must carry the same code.
90 if (prev != line_code) return error.InvalidReply;
91 } else {
92 code = line_code;
93 }
94 var last = true;
95 var line_text: []const u8 = "";
96 if (line.len > 3) {
97 switch (line[3]) {
98 ' ' => {},
99 '-' => last = false,
100 else => return error.InvalidReply,
101 }
102 line_text = line[4..];
103 }
104 if (!first) text.writeByte('\n') catch return error.ReplyTooLong;
105 text.writeAll(line_text) catch return error.ReplyTooLong;
106 first = false;
107 if (last) break;
108 }
109 return .{ .code = code.?, .text = text.buffered() };
110 }
111
112 /// Iterates over the individual text lines of the reply.
113 pub fn lines(r: *const Reply) std.mem.SplitIterator(u8, .scalar) {
114 return std.mem.splitScalar(u8, r.text, '\n');
115 }
116
117 // Reply classes per RFC 5321 §4.2.1
118 // (https://datatracker.ietf.org/doc/html/rfc5321#section-4.2.1).
119 pub fn isPositiveCompletion(r: Reply) bool {
120 return r.code >= 200 and r.code < 300;
121 }
122 pub fn isPositiveIntermediate(r: Reply) bool {
123 return r.code >= 300 and r.code < 400;
124 }
125 pub fn isTransientFailure(r: Reply) bool {
126 return r.code >= 400 and r.code < 500;
127 }
128 pub fn isPermanentFailure(r: Reply) bool {
129 return r.code >= 500 and r.code < 600;
130 }
131
132 test read {
133 var reader: Io.Reader = .fixed("250-first\r\n250 second\r\n");
134 var buffer: [64]u8 = undefined;
135 const reply = try read(&reader, &buffer);
136 try std.testing.expectEqual(@as(u16, 250), reply.code);
137 try std.testing.expectEqualStrings("first\nsecond", reply.text);
138 }
139
140 test lines {
141 const reply: Reply = .{ .code = 250, .text = "one\ntwo" };
142 var it = reply.lines();
143 try std.testing.expectEqualStrings("one", it.next().?);
144 try std.testing.expectEqualStrings("two", it.next().?);
145 try std.testing.expectEqual(@as(?[]const u8, null), it.next());
146 }
147
148 test isPositiveCompletion {
149 try std.testing.expect((Reply{ .code = 250, .text = "" }).isPositiveCompletion());
150 try std.testing.expect(!(Reply{ .code = 354, .text = "" }).isPositiveCompletion());
151 }
152
153 test isPositiveIntermediate {
154 try std.testing.expect((Reply{ .code = 354, .text = "" }).isPositiveIntermediate());
155 }
156
157 test isTransientFailure {
158 try std.testing.expect((Reply{ .code = 451, .text = "" }).isTransientFailure());
159 }
160
161 test isPermanentFailure {
162 try std.testing.expect((Reply{ .code = 550, .text = "" }).isPermanentFailure());
163 }
164};
165
166/// A parsed client command, as seen by a server.
167pub const Command = union(enum) {
168 helo: []const u8,
169 ehlo: []const u8,
170 /// LHLO, the LMTP greeting
171 /// ([RFC 2033](https://datatracker.ietf.org/doc/html/rfc2033)), which
172 /// has the same semantics as EHLO. An LMTP server takes this one and
173 /// refuses HELO and EHLO; an SMTP server does the reverse.
174 lhlo: []const u8,
175 /// MAIL FROM. An empty path is the null reverse-path (`MAIL FROM:<>`).
176 mail: PathArgs,
177 /// RCPT TO.
178 rcpt: PathArgs,
179 data,
180 rset,
181 noop,
182 quit,
183 vrfy: []const u8,
184 help,
185 starttls,
186 /// AUTH ([RFC 4954](https://datatracker.ietf.org/doc/html/rfc4954)).
187 auth: AuthArgs,
188 /// BDAT, the CHUNKING extension
189 /// ([RFC 3030](https://datatracker.ietf.org/doc/html/rfc3030)). The
190 /// command line is followed by exactly `size` raw octets.
191 bdat: BdatArgs,
192 /// Unrecognized command verb; the payload is the full line.
193 unknown: []const u8,
194
195 pub const BdatArgs = struct {
196 size: u64,
197 /// True for the final chunk of the message ("BDAT n LAST").
198 last: bool = false,
199 };
200
201 pub const AuthArgs = struct {
202 mechanism: []const u8,
203 /// Raw base64 initial response, if the client sent one ("=" denotes
204 /// an empty initial response).
205 initial: []const u8 = "",
206 };
207
208 pub const PathArgs = struct {
209 /// The mailbox, with angle brackets and any obsolete source route
210 /// stripped.
211 path: []const u8,
212 /// Raw ESMTP parameters that followed the path, e.g. "SIZE=1024".
213 params: []const u8 = "",
214
215 pub fn paramIterator(args: PathArgs) ParamIterator {
216 return .init(args.params);
217 }
218
219 test paramIterator {
220 const args: PathArgs = .{ .path = "a@example.com", .params = "SIZE=7" };
221 var it = args.paramIterator();
222 try std.testing.expectEqualStrings("SIZE", it.next().?.keyword);
223 }
224 };
225
226 pub const ParseError = error{Syntax};
227
228 /// Parses one command line (without its line ending). Returned slices
229 /// point into `line`.
230 pub fn parse(line: []const u8) ParseError!Command {
231 const trimmed = std.mem.trim(u8, line, " \t");
232 const verb_end = std.mem.indexOfAny(u8, trimmed, " \t") orelse trimmed.len;
233 const verb = trimmed[0..verb_end];
234 const rest = std.mem.trimStart(u8, trimmed[verb_end..], " \t");
235
236 if (ieql(verb, "HELO")) {
237 if (rest.len == 0) return error.Syntax;
238 return .{ .helo = rest };
239 }
240 if (ieql(verb, "EHLO")) {
241 if (rest.len == 0) return error.Syntax;
242 return .{ .ehlo = rest };
243 }
244 if (ieql(verb, "LHLO")) {
245 if (rest.len == 0) return error.Syntax;
246 return .{ .lhlo = rest };
247 }
248 if (ieql(verb, "MAIL")) return .{ .mail = try parsePathArgs(rest, "FROM:") };
249 if (ieql(verb, "RCPT")) return .{ .rcpt = try parsePathArgs(rest, "TO:") };
250 if (ieql(verb, "DATA")) return .data;
251 if (ieql(verb, "RSET")) return .rset;
252 if (ieql(verb, "NOOP")) return .noop;
253 if (ieql(verb, "QUIT")) return .quit;
254 if (ieql(verb, "VRFY")) return .{ .vrfy = rest };
255 if (ieql(verb, "HELP")) return .help;
256 if (ieql(verb, "STARTTLS")) return .starttls;
257 if (ieql(verb, "BDAT")) {
258 var it = std.mem.tokenizeAny(u8, rest, " \t");
259 const size_token = it.next() orelse return error.Syntax;
260 const size = std.fmt.parseInt(u64, size_token, 10) catch return error.Syntax;
261 var last = false;
262 if (it.next()) |token| {
263 if (!ieql(token, "LAST")) return error.Syntax;
264 last = true;
265 }
266 if (it.next() != null) return error.Syntax;
267 return .{ .bdat = .{ .size = size, .last = last } };
268 }
269 if (ieql(verb, "AUTH")) {
270 const mech_end = std.mem.indexOfAny(u8, rest, " \t") orelse rest.len;
271 if (mech_end == 0) return error.Syntax;
272 return .{ .auth = .{
273 .mechanism = rest[0..mech_end],
274 .initial = std.mem.trimStart(u8, rest[mech_end..], " \t"),
275 } };
276 }
277 return .{ .unknown = line };
278 }
279
280 fn parsePathArgs(rest: []const u8, comptime keyword: []const u8) ParseError!PathArgs {
281 if (rest.len < keyword.len or !ieql(rest[0..keyword.len], keyword))
282 return error.Syntax;
283 const after = std.mem.trimStart(u8, rest[keyword.len..], " \t");
284 if (after.len == 0 or after[0] != '<') {
285 // Lenient: accept a bare address ending at whitespace.
286 const end = std.mem.indexOfAny(u8, after, " \t") orelse after.len;
287 if (end == 0) return error.Syntax;
288 return .{
289 .path = after[0..end],
290 .params = std.mem.trimStart(u8, after[end..], " \t"),
291 };
292 }
293 // The closing bracket must be found outside any quoted local-part:
294 // <"a>b"@example.com> is legal (RFC 5321 quoted-string, with
295 // backslash escapes).
296 const close = close: {
297 var in_quotes = false;
298 var i: usize = 1;
299 while (i < after.len) : (i += 1) {
300 const byte = after[i];
301 if (in_quotes) {
302 if (byte == '\\') {
303 i += 1;
304 } else if (byte == '"') {
305 in_quotes = false;
306 }
307 } else if (byte == '"') {
308 in_quotes = true;
309 } else if (byte == '>') {
310 break :close i;
311 }
312 }
313 return error.Syntax;
314 };
315 var path = after[1..close];
316 // Strip an obsolete source route: <@relay1,@relay2:user@host>.
317 if (path.len > 0 and path[0] == '@') {
318 const colon = std.mem.indexOfScalar(u8, path, ':') orelse return error.Syntax;
319 path = path[colon + 1 ..];
320 }
321 return .{
322 .path = path,
323 .params = std.mem.trimStart(u8, after[close + 1 ..], " \t"),
324 };
325 }
326
327 fn ieql(a: []const u8, b: []const u8) bool {
328 return std.ascii.eqlIgnoreCase(a, b);
329 }
330
331 test parse {
332 const command = try parse("RCPT TO:<bob@example.net>");
333 try std.testing.expectEqualStrings("bob@example.net", command.rcpt.path);
334 try std.testing.expectError(error.Syntax, parse("MAIL <missing-keyword>"));
335 }
336};
337
338/// The `RET` parameter of an extended MAIL command
339/// ([RFC 3461 §4.3](https://datatracker.ietf.org/doc/html/rfc3461#section-4.3)):
340/// how much of the message a failed DSN should carry back. Absent, the
341/// choice is the reporting MTA's.
342/// The `BODY` parameter of an extended MAIL command: what kind of content
343/// the message carries, and so what the receiver has to be able to take.
344pub const Body = enum {
345 /// [RFC 6152](https://datatracker.ietf.org/doc/html/rfc6152). Lines of
346 /// at most 998 characters from the ASCII repertoire.
347 seven_bit,
348 /// [RFC 6152](https://datatracker.ietf.org/doc/html/rfc6152). The same
349 /// line structure, with the high bit allowed.
350 eight_bit_mime,
351 /// [RFC 3030](https://datatracker.ietf.org/doc/html/rfc3030). Arbitrary
352 /// octets with no line structure at all, which is why it can only be
353 /// carried by BDAT: DATA has no way to frame content that may hold the
354 /// terminator itself.
355 binary_mime,
356
357 pub const ParseError = error{Syntax};
358
359 pub fn parse(value: []const u8) ParseError!Body {
360 if (std.ascii.eqlIgnoreCase(value, "7BIT")) return .seven_bit;
361 if (std.ascii.eqlIgnoreCase(value, "8BITMIME")) return .eight_bit_mime;
362 if (std.ascii.eqlIgnoreCase(value, "BINARYMIME")) return .binary_mime;
363 return error.Syntax;
364 }
365
366 /// Writes the value as it appears on the wire.
367 pub fn format(b: Body, writer: *Io.Writer) Io.Writer.Error!void {
368 try writer.writeAll(switch (b) {
369 .seven_bit => "7BIT",
370 .eight_bit_mime => "8BITMIME",
371 .binary_mime => "BINARYMIME",
372 });
373 }
374
375 test parse {
376 try std.testing.expectEqual(Body.binary_mime, try parse("binarymime"));
377 try std.testing.expectEqual(Body.seven_bit, try parse("7BIT"));
378 try std.testing.expectError(error.Syntax, parse("BINARY"));
379 }
380};
381
382/// RFC 3461 §4.4 caps the `ENVID` parameter value at 100 characters, which
383/// is a limit on the xtext-encoded form and not on what went into it.
384pub const max_envid_len = 100;
385
386pub const Ret = enum {
387 /// Return the entire message.
388 full,
389 /// Return the headers only.
390 hdrs,
391
392 pub const ParseError = error{Syntax};
393
394 pub fn parse(value: []const u8) ParseError!Ret {
395 if (std.ascii.eqlIgnoreCase(value, "FULL")) return .full;
396 if (std.ascii.eqlIgnoreCase(value, "HDRS")) return .hdrs;
397 return error.Syntax;
398 }
399
400 /// Writes the value as it appears on the wire.
401 pub fn format(r: Ret, writer: *Io.Writer) Io.Writer.Error!void {
402 try writer.writeAll(switch (r) {
403 .full => "FULL",
404 .hdrs => "HDRS",
405 });
406 }
407
408 test parse {
409 try std.testing.expectEqual(Ret.hdrs, try parse("hdrs"));
410 try std.testing.expectError(error.Syntax, parse("PARTIAL"));
411 }
412};
413
414/// The `NOTIFY` parameter of an extended RCPT command
415/// ([RFC 3461 §4.1](https://datatracker.ietf.org/doc/html/rfc3461#section-4.1)):
416/// the conditions under which the sender wants to hear about this
417/// recipient. Absent, RFC 3461 lets a server read it as either
418/// `FAILURE` or `FAILURE,DELAY` — which is why "not specified" is an
419/// absent `?Notify` here and not a value of it.
420pub const Notify = union(enum) {
421 /// `NOTIFY=NEVER`: no DSN for this recipient under any circumstance.
422 /// RFC 3461 requires the keyword to appear on its own, and parsing
423 /// rejects it in a list.
424 never,
425 /// One or more of `SUCCESS`, `FAILURE` and `DELAY`.
426 on: Conditions,
427
428 pub const Conditions = struct {
429 success: bool = false,
430 failure: bool = false,
431 delay: bool = false,
432 };
433
434 pub const ParseError = error{Syntax};
435
436 pub fn parse(value: []const u8) ParseError!Notify {
437 if (std.ascii.eqlIgnoreCase(value, "NEVER")) return .never;
438 var conditions: Conditions = .{};
439 var it = std.mem.splitScalar(u8, value, ',');
440 var any = false;
441 while (it.next()) |keyword| {
442 if (std.ascii.eqlIgnoreCase(keyword, "SUCCESS")) {
443 conditions.success = true;
444 } else if (std.ascii.eqlIgnoreCase(keyword, "FAILURE")) {
445 conditions.failure = true;
446 } else if (std.ascii.eqlIgnoreCase(keyword, "DELAY")) {
447 conditions.delay = true;
448 } else return error.Syntax; // Including NEVER: it may not be listed.
449 any = true;
450 }
451 if (!any) return error.Syntax;
452 return .{ .on = conditions };
453 }
454
455 /// Writes the value as it appears on the wire.
456 pub fn format(n: Notify, writer: *Io.Writer) Io.Writer.Error!void {
457 switch (n) {
458 .never => try writer.writeAll("NEVER"),
459 .on => |conditions| {
460 var written = false;
461 inline for (.{
462 .{ conditions.success, "SUCCESS" },
463 .{ conditions.failure, "FAILURE" },
464 .{ conditions.delay, "DELAY" },
465 }) |pair| {
466 if (pair[0]) {
467 if (written) try writer.writeByte(',');
468 try writer.writeAll(pair[1]);
469 written = true;
470 }
471 }
472 // An empty condition set has no legal spelling; NEVER is
473 // what "tell me nothing" is written as.
474 if (!written) try writer.writeAll("NEVER");
475 },
476 }
477 }
478
479 test parse {
480 try std.testing.expectEqual(Notify.never, try parse("NEVER"));
481 const both = try parse("SUCCESS,delay");
482 try std.testing.expect(both.on.success and both.on.delay and !both.on.failure);
483 try std.testing.expectError(error.Syntax, parse("NEVER,SUCCESS"));
484 try std.testing.expectError(error.Syntax, parse(""));
485 try std.testing.expectError(error.Syntax, parse("SUCCESS,MAYBE"));
486 }
487};
488
489/// The `ORCPT` parameter of an extended RCPT command
490/// ([RFC 3461 §4.2](https://datatracker.ietf.org/doc/html/rfc3461#section-4.2)):
491/// the address the message was originally addressed to, carried unchanged
492/// through aliasing and forwarding so that a DSN can name what the sender
493/// actually wrote.
494pub const Orcpt = struct {
495 /// The address type, an atom — `rfc822` in all but the unusual cases.
496 addr_type: []const u8,
497 /// The original recipient, xtext-decoded.
498 address: []const u8,
499
500 /// RFC 3461 §4.2 caps the whole parameter value at 500 characters.
501 pub const max_len = 500;
502
503 pub const ParseError = error{Syntax};
504
505 /// Parses `addr-type ";" xtext`, decoding the address into `buffer`.
506 /// The returned `addr_type` points into `value` and `address` points
507 /// into `buffer`, so the two have different lifetimes; a caller keeping
508 /// the result past either one copies both.
509 pub fn parse(buffer: []u8, value: []const u8) ParseError!Orcpt {
510 const semicolon = std.mem.findScalar(u8, value, ';') orelse return error.Syntax;
511 const addr_type = value[0..semicolon];
512 if (addr_type.len == 0) return error.Syntax;
513 for (addr_type) |byte| if (!isAtomByte(byte)) return error.Syntax;
514 return .{
515 .addr_type = addr_type,
516 .address = xtextDecode(buffer, value[semicolon + 1 ..]) catch return error.Syntax,
517 };
518 }
519
520 /// Writes the parameter value as it appears on the wire, xtext-encoding
521 /// the address.
522 pub fn format(o: Orcpt, writer: *Io.Writer) Io.Writer.Error!void {
523 try writer.writeAll(o.addr_type);
524 try writer.writeByte(';');
525 try writeXtext(writer, o.address);
526 }
527
528 /// RFC 5321 `atom` less the specials, which is what an addr-type may be.
529 fn isAtomByte(byte: u8) bool {
530 return switch (byte) {
531 'A'...'Z', 'a'...'z', '0'...'9' => true,
532 '!', '#', '$', '%', '&', '\'', '*', '+', '-', '/', '=', '?' => true,
533 '^', '_', '`', '{', '|', '}', '~' => true,
534 else => false,
535 };
536 }
537
538 test parse {
539 var buffer: [64]u8 = undefined;
540 const orcpt = try parse(&buffer, "rfc822;bob+2Bx@example.net");
541 try std.testing.expectEqualStrings("rfc822", orcpt.addr_type);
542 try std.testing.expectEqualStrings("bob+x@example.net", orcpt.address);
543 try std.testing.expectError(error.Syntax, parse(&buffer, "bob@example.net"));
544 try std.testing.expectError(error.Syntax, parse(&buffer, ";bob@example.net"));
545 }
546};
547
548/// Whether `byte` may appear in an xtext unencoded
549/// ([RFC 3461 §4](https://datatracker.ietf.org/doc/html/rfc3461#section-4)):
550/// printable US-ASCII other than `+`, which introduces an escape, and `=`,
551/// which separates an ESMTP keyword from its value.
552pub fn isXchar(byte: u8) bool {
553 return byte >= '!' and byte <= '~' and byte != '+' and byte != '=';
554}
555
556/// Writes `text` xtext-encoded: anything that is not an `xchar` becomes
557/// `+` and two upper-case hex digits. Every byte therefore survives,
558/// including the ones that would otherwise end the command line, so an
559/// xtext-encoded parameter is safe to write from untrusted input.
560///
561/// RFC 3461 asks that the value before encoding be printable US-ASCII.
562/// That is the caller's to observe; encoding anything else here produces
563/// valid xtext regardless rather than a corrupt command.
564pub fn writeXtext(writer: *Io.Writer, text: []const u8) Io.Writer.Error!void {
565 for (text) |byte| {
566 if (isXchar(byte)) {
567 try writer.writeByte(byte);
568 } else {
569 try writer.print("+{X:0>2}", .{byte});
570 }
571 }
572}
573
574/// The length `writeXtext` will produce for `text`, for checking a value
575/// against the length limits RFC 3461 puts on the encoded form.
576pub fn xtextEncodedLen(text: []const u8) usize {
577 var len: usize = 0;
578 for (text) |byte| len += if (isXchar(byte)) 1 else 3;
579 return len;
580}
581
582pub const XtextError = error{
583 /// Not valid xtext: a `+` not followed by two hex digits, or a raw byte
584 /// that the encoder was required to escape.
585 BadXtext,
586 NoSpaceLeft,
587};
588
589/// Decodes xtext into `buffer`, returning the decoded bytes. Decoding is
590/// strict: a byte an encoder was obliged to escape is rejected rather than
591/// passed through, since accepting it would let two different encodings
592/// mean the same thing.
593pub fn xtextDecode(buffer: []u8, text: []const u8) XtextError![]u8 {
594 var out: usize = 0;
595 var i: usize = 0;
596 while (i < text.len) {
597 const byte = text[i];
598 if (byte == '+') {
599 if (i + 2 >= text.len) return error.BadXtext;
600 const hex = text[i + 1 ..][0..2];
601 // Checked before parsing because `parseInt` also accepts a sign
602 // and underscore separators, which hex digits are not. Lower
603 // case is accepted on the way in even though RFC 3461 requires
604 // upper case on the way out.
605 for (hex) |digit| if (!std.ascii.isHex(digit)) return error.BadXtext;
606 const value = std.fmt.parseInt(u8, hex, 16) catch return error.BadXtext;
607 if (out >= buffer.len) return error.NoSpaceLeft;
608 buffer[out] = value;
609 out += 1;
610 i += 3;
611 } else {
612 if (!isXchar(byte)) return error.BadXtext;
613 if (out >= buffer.len) return error.NoSpaceLeft;
614 buffer[out] = byte;
615 out += 1;
616 i += 1;
617 }
618 }
619 return buffer[0..out];
620}
621
622test xtextDecode {
623 var buffer: [64]u8 = undefined;
624 try std.testing.expectEqualStrings(
625 "a+b=c",
626 try xtextDecode(&buffer, "a+2Bb+3Dc"),
627 );
628 try std.testing.expectError(error.BadXtext, xtextDecode(&buffer, "a+2"));
629 try std.testing.expectError(error.BadXtext, xtextDecode(&buffer, "a+ZZb"));
630 // A raw '=' or ' ' is what the encoder had to escape.
631 try std.testing.expectError(error.BadXtext, xtextDecode(&buffer, "a=b"));
632 try std.testing.expectError(error.BadXtext, xtextDecode(&buffer, "a b"));
633}
634
635test writeXtext {
636 var out_buf: [64]u8 = undefined;
637 var writer: Io.Writer = .fixed(&out_buf);
638 try writeXtext(&writer, "id+1=2 \r\n");
639 try std.testing.expectEqualStrings("id+2B1+3D2+20+0D+0A", writer.buffered());
640 try std.testing.expectEqual(writer.buffered().len, xtextEncodedLen("id+1=2 \r\n"));
641
642 // Every byte survives the round trip.
643 var raw: [256]u8 = undefined;
644 for (&raw, 0..) |*byte, i| byte.* = @intCast(i);
645 var round_buf: [1024]u8 = undefined;
646 var round: Io.Writer = .fixed(&round_buf);
647 try writeXtext(&round, &raw);
648 var decoded_buf: [256]u8 = undefined;
649 try std.testing.expectEqualSlices(u8, &raw, try xtextDecode(&decoded_buf, round.buffered()));
650}
651
652/// Iterates the ESMTP parameters of a MAIL or RCPT command
653/// ([RFC 5321 §4.1.2](https://datatracker.ietf.org/doc/html/rfc5321#section-4.1.2)),
654/// e.g. "SIZE=1024 BODY=8BITMIME".
655pub const ParamIterator = struct {
656 rest: []const u8,
657
658 pub const Param = struct {
659 keyword: []const u8,
660 /// Empty when the parameter carries no value.
661 value: []const u8 = "",
662 };
663
664 pub fn init(params: []const u8) ParamIterator {
665 return .{ .rest = params };
666 }
667
668 pub fn next(it: *ParamIterator) ?Param {
669 it.rest = std.mem.trimStart(u8, it.rest, " \t");
670 if (it.rest.len == 0) return null;
671 const end = std.mem.indexOfAny(u8, it.rest, " \t") orelse it.rest.len;
672 const token = it.rest[0..end];
673 it.rest = it.rest[end..];
674 if (std.mem.indexOfScalar(u8, token, '=')) |eq| {
675 return .{ .keyword = token[0..eq], .value = token[eq + 1 ..] };
676 }
677 return .{ .keyword = token };
678 }
679
680 test init {
681 var it: ParamIterator = .init("SIZE=42");
682 try std.testing.expectEqualStrings("SIZE", it.next().?.keyword);
683 }
684
685 test next {
686 var it: ParamIterator = .init("BODY=8BITMIME CUSTOM");
687 const body = it.next().?;
688 try std.testing.expectEqualStrings("BODY", body.keyword);
689 try std.testing.expectEqualStrings("8BITMIME", body.value);
690 const custom = it.next().?;
691 try std.testing.expectEqualStrings("CUSTOM", custom.keyword);
692 try std.testing.expectEqualStrings("", custom.value);
693 try std.testing.expectEqual(@as(?Param, null), it.next());
694 }
695};
696
697/// Writes `data` as SMTP message content: line endings are normalized to CRLF
698/// and lines beginning with '.' are dot-stuffed
699/// ([RFC 5321 §4.5.2](https://datatracker.ietf.org/doc/html/rfc5321#section-4.5.2)). Does not
700/// write the terminating ".\r\n".
701pub fn writeStuffed(writer: *Io.Writer, data: []const u8) Io.Writer.Error!void {
702 var rest = data;
703 while (rest.len > 0) {
704 var line: []const u8 = undefined;
705 if (std.mem.indexOfScalar(u8, rest, '\n')) |i| {
706 line = rest[0..i];
707 rest = rest[i + 1 ..];
708 } else {
709 line = rest;
710 rest = rest[rest.len..];
711 }
712 if (line.len > 0 and line[line.len - 1] == '\r') line = line[0 .. line.len - 1];
713 if (line.len > 0 and line[0] == '.') try writer.writeByte('.');
714 try writer.writeAll(line);
715 try writer.writeAll(crlf);
716 }
717}
718
719test readLine {
720 var reader: Io.Reader = .fixed("first\r\nsecond\nthird\r\n");
721 try std.testing.expectEqualStrings("first", try readLine(&reader));
722 try std.testing.expectEqualStrings("second", try readLine(&reader));
723 try std.testing.expectEqualStrings("third", try readLine(&reader));
724 try std.testing.expectError(error.EndOfStream, readLine(&reader));
725}
726
727test Reply {
728 var reader: Io.Reader = .fixed("250 2.0.0 Ok\r\n");
729 var buf: [128]u8 = undefined;
730 const reply = try Reply.read(&reader, &buf);
731 try std.testing.expectEqual(@as(u16, 250), reply.code);
732 try std.testing.expectEqualStrings("2.0.0 Ok", reply.text);
733 try std.testing.expect(reply.isPositiveCompletion());
734}
735
736test "Reply.read multiline" {
737 var reader: Io.Reader = .fixed("250-mx.example.com\r\n250-PIPELINING\r\n250 SIZE 1000\r\n");
738 var buf: [128]u8 = undefined;
739 const reply = try Reply.read(&reader, &buf);
740 try std.testing.expectEqual(@as(u16, 250), reply.code);
741 try std.testing.expectEqualStrings("mx.example.com\nPIPELINING\nSIZE 1000", reply.text);
742 var it = reply.lines();
743 try std.testing.expectEqualStrings("mx.example.com", it.next().?);
744 try std.testing.expectEqualStrings("PIPELINING", it.next().?);
745 try std.testing.expectEqualStrings("SIZE 1000", it.next().?);
746 try std.testing.expectEqual(@as(?[]const u8, null), it.next());
747}
748
749test "Reply.read rejects malformed replies" {
750 var buf: [128]u8 = undefined;
751 {
752 var reader: Io.Reader = .fixed("2x0 hello\r\n");
753 try std.testing.expectError(error.InvalidReply, Reply.read(&reader, &buf));
754 }
755 {
756 var reader: Io.Reader = .fixed("250-one\r\n251 two\r\n");
757 try std.testing.expectError(error.InvalidReply, Reply.read(&reader, &buf));
758 }
759 {
760 var reader: Io.Reader = .fixed("42\r\n");
761 try std.testing.expectError(error.InvalidReply, Reply.read(&reader, &buf));
762 }
763}
764
765test Command {
766 {
767 const cmd = try Command.parse("EHLO client.example.com");
768 try std.testing.expectEqualStrings("client.example.com", cmd.ehlo);
769 }
770 {
771 const cmd = try Command.parse("mail from:<alice@example.com> SIZE=1024");
772 try std.testing.expectEqualStrings("alice@example.com", cmd.mail.path);
773 try std.testing.expectEqualStrings("SIZE=1024", cmd.mail.params);
774 }
775 {
776 // Null reverse-path and a space after the colon.
777 const cmd = try Command.parse("MAIL FROM: <>");
778 try std.testing.expectEqualStrings("", cmd.mail.path);
779 }
780 {
781 // Obsolete source route is stripped.
782 const cmd = try Command.parse("RCPT TO:<@relay.example:bob@example.net>");
783 try std.testing.expectEqualStrings("bob@example.net", cmd.rcpt.path);
784 }
785 {
786 // Quoted local-parts (from postfix's address corpora) may contain
787 // spaces and even '>' or escaped quotes.
788 const cmd = try Command.parse("MAIL FROM:<\"foo bar\"@example.com> SIZE=9");
789 try std.testing.expectEqualStrings("\"foo bar\"@example.com", cmd.mail.path);
790 try std.testing.expectEqualStrings("SIZE=9", cmd.mail.params);
791 }
792 {
793 const cmd = try Command.parse("RCPT TO:<\"a>b\"@example.com>");
794 try std.testing.expectEqualStrings("\"a>b\"@example.com", cmd.rcpt.path);
795 }
796 {
797 const cmd = try Command.parse("RCPT TO:<\"a\\\">b\"@example.com>");
798 try std.testing.expectEqualStrings("\"a\\\">b\"@example.com", cmd.rcpt.path);
799 }
800 try std.testing.expectError(error.Syntax, Command.parse("MAIL FROM:<\"unterminated@example.com>"));
801 {
802 const cmd = try Command.parse("QUIT");
803 try std.testing.expectEqual(Command.quit, cmd);
804 }
805 {
806 const cmd = try Command.parse("AUTH PLAIN AHVzZXIAcGFzcw==");
807 try std.testing.expectEqualStrings("PLAIN", cmd.auth.mechanism);
808 try std.testing.expectEqualStrings("AHVzZXIAcGFzcw==", cmd.auth.initial);
809 }
810 {
811 const cmd = try Command.parse("auth login");
812 try std.testing.expectEqualStrings("login", cmd.auth.mechanism);
813 try std.testing.expectEqualStrings("", cmd.auth.initial);
814 }
815 {
816 const cmd = try Command.parse("MADE UP");
817 try std.testing.expectEqualStrings("MADE UP", cmd.unknown);
818 }
819 {
820 const cmd = try Command.parse("BDAT 1024");
821 try std.testing.expectEqual(@as(u64, 1024), cmd.bdat.size);
822 try std.testing.expect(!cmd.bdat.last);
823 }
824 {
825 const cmd = try Command.parse("bdat 0 last");
826 try std.testing.expectEqual(@as(u64, 0), cmd.bdat.size);
827 try std.testing.expect(cmd.bdat.last);
828 }
829 try std.testing.expectError(error.Syntax, Command.parse("BDAT"));
830 try std.testing.expectError(error.Syntax, Command.parse("BDAT nan"));
831 try std.testing.expectError(error.Syntax, Command.parse("BDAT 5 FIRST"));
832 try std.testing.expectError(error.Syntax, Command.parse("BDAT 5 LAST extra"));
833 try std.testing.expectError(error.Syntax, Command.parse("AUTH"));
834 try std.testing.expectError(error.Syntax, Command.parse("MAIL TO:<a@b>"));
835 try std.testing.expectError(error.Syntax, Command.parse("RCPT TO:"));
836 try std.testing.expectError(error.Syntax, Command.parse("HELO"));
837}
838
839test writeStuffed {
840 var buf: [256]u8 = undefined;
841 {
842 var w: Io.Writer = .fixed(&buf);
843 try writeStuffed(&w, "line one\r\n.starts with dot\r\n");
844 try std.testing.expectEqualStrings("line one\r\n..starts with dot\r\n", w.buffered());
845 }
846 {
847 // LF-only input is normalized, missing final newline is added.
848 var w: Io.Writer = .fixed(&buf);
849 try writeStuffed(&w, "a\nb");
850 try std.testing.expectEqualStrings("a\r\nb\r\n", w.buffered());
851 }
852 {
853 // A lone "." line must not become a terminator.
854 var w: Io.Writer = .fixed(&buf);
855 try writeStuffed(&w, ".\n");
856 try std.testing.expectEqualStrings("..\r\n", w.buffered());
857 }
858 {
859 var w: Io.Writer = .fixed(&buf);
860 try writeStuffed(&w, "");
861 try std.testing.expectEqualStrings("", w.buffered());
862 }
863}
864
865test "fuzz Command.parse" {
866 try std.testing.fuzz({}, fuzzCommandParse, .{});
867}
868
869fn fuzzCommandParse(context: void, smith: *std.testing.Smith) !void {
870 _ = context;
871 var line_buf: [512]u8 = undefined;
872 const line = line_buf[0..smith.value(u9)];
873 smith.bytes(line);
874
875 const command = Command.parse(line) catch return;
876 // Payload slices must always lie within the parsed line.
877 switch (command) {
878 .helo, .ehlo, .lhlo, .vrfy, .unknown => |payload| try std.testing.expect(payload.len <= line.len),
879 .mail, .rcpt => |args| {
880 try std.testing.expect(args.path.len <= line.len);
881 try std.testing.expect(args.params.len <= line.len);
882 },
883 .auth => |args| {
884 try std.testing.expect(args.mechanism.len <= line.len);
885 try std.testing.expect(args.initial.len <= line.len);
886 },
887 .data, .rset, .noop, .quit, .help, .starttls, .bdat => {},
888 }
889}
890
891test "fuzz Reply.read" {
892 try std.testing.fuzz({}, fuzzReplyRead, .{});
893}
894
895fn fuzzReplyRead(context: void, smith: *std.testing.Smith) !void {
896 _ = context;
897 var input_buf: [1024]u8 = undefined;
898 const input = input_buf[0..smith.value(u10)];
899 smith.bytes(input);
900
901 var reader: Io.Reader = .fixed(input);
902 var text_buf: [128]u8 = undefined;
903 // Each successful read consumes at least one line, so this terminates.
904 while (true) {
905 const reply = Reply.read(&reader, &text_buf) catch break;
906 try std.testing.expect(reply.code >= 100 and reply.code <= 599);
907 }
908}
909
910test ParamIterator {
911 const command = try Command.parse("MAIL FROM:<a@example.com> SIZE=1024 BODY=8BITMIME FLAG");
912 var it = command.mail.paramIterator();
913
914 const size = it.next().?;
915 try std.testing.expectEqualStrings("SIZE", size.keyword);
916 try std.testing.expectEqualStrings("1024", size.value);
917
918 const body = it.next().?;
919 try std.testing.expectEqualStrings("BODY", body.keyword);
920 try std.testing.expectEqualStrings("8BITMIME", body.value);
921
922 const flag = it.next().?;
923 try std.testing.expectEqualStrings("FLAG", flag.keyword);
924 try std.testing.expectEqualStrings("", flag.value);
925
926 try std.testing.expectEqual(@as(?ParamIterator.Param, null), it.next());
927}
928
929test crlf {
930 try std.testing.expectEqualStrings("\r\n", crlf);
931}
932
933test "RFC 5321 mailbox forms from the is_email corpus round-trip" {
934 // Parses Dominic Sayers' is_email test suite (tests.xml and
935 // tests-original.xml, embedded from the lazy `isemail` dependency by
936 // `zig build test -Disemail-corpus`) and checks that every address
937 // valid at the RFC 5321 layer passes through the lenient path parser
938 // byte-for-byte, params intact.
939 if (comptime @import("build_options").isemail_corpus) {
940 const corpus = @embedFile("isemail_tests_xml") ++ "\n" ++
941 @embedFile("isemail_tests_original_xml");
942 var checked: usize = 0;
943 var rest: []const u8 = corpus;
944 while (std.mem.indexOf(u8, rest, "<test ")) |start_index| {
945 const end_index = std.mem.indexOfPos(u8, rest, start_index, "</test>") orelse break;
946 const block = rest[start_index..end_index];
947 rest = rest[end_index + "</test>".len ..];
948
949 const category = xmlElementText(block, "category") orelse continue;
950 if (!std.mem.eql(u8, category, "ISEMAIL_VALID_CATEGORY") and
951 !std.mem.eql(u8, category, "ISEMAIL_RFC5321")) continue;
952 const raw = xmlElementText(block, "address") orelse continue;
953 var address_buf: [256]u8 = undefined;
954 const address = try xmlUnescape(&address_buf, raw);
955
956 var line_buf: [300]u8 = undefined;
957 const line = try std.fmt.bufPrint(&line_buf, "MAIL FROM:<{s}> SIZE=1", .{address});
958 const command = try Command.parse(line);
959 try std.testing.expectEqualStrings(address, command.mail.path);
960 try std.testing.expectEqualStrings("SIZE=1", command.mail.params);
961 checked += 1;
962 }
963 // The two files carry 125 RFC 5321-valid cases between them; fail
964 // loudly if the extraction ever silently rots.
965 try std.testing.expect(checked >= 120);
966 } else return error.SkipZigTest;
967}
968
969fn xmlElementText(block: []const u8, comptime tag: []const u8) ?[]const u8 {
970 const open = "<" ++ tag ++ ">";
971 const close = "</" ++ tag ++ ">";
972 const start = (std.mem.indexOf(u8, block, open) orelse return null) + open.len;
973 const end = std.mem.indexOfPos(u8, block, start, close) orelse return null;
974 return block[start..end];
975}
976
977fn xmlUnescape(buffer: []u8, input: []const u8) ![]const u8 {
978 var out: usize = 0;
979 var i: usize = 0;
980 while (i < input.len) {
981 if (input[i] != '&') {
982 buffer[out] = input[i];
983 out += 1;
984 i += 1;
985 continue;
986 }
987 const semi = std.mem.indexOfScalarPos(u8, input, i, ';') orelse return error.BadEntity;
988 const entity = input[i + 1 .. semi];
989 i = semi + 1;
990 if (std.mem.eql(u8, entity, "amp")) {
991 buffer[out] = '&';
992 out += 1;
993 } else if (std.mem.eql(u8, entity, "lt")) {
994 buffer[out] = '<';
995 out += 1;
996 } else if (std.mem.eql(u8, entity, "gt")) {
997 buffer[out] = '>';
998 out += 1;
999 } else if (std.mem.eql(u8, entity, "quot")) {
1000 buffer[out] = '"';
1001 out += 1;
1002 } else if (std.mem.eql(u8, entity, "apos")) {
1003 buffer[out] = '\'';
1004 out += 1;
1005 } else if (std.mem.startsWith(u8, entity, "#x") or std.mem.startsWith(u8, entity, "#X")) {
1006 const codepoint = try std.fmt.parseInt(u21, entity[2..], 16);
1007 out += try std.unicode.utf8Encode(codepoint, buffer[out..]);
1008 } else if (std.mem.startsWith(u8, entity, "#")) {
1009 const codepoint = try std.fmt.parseInt(u21, entity[1..], 10);
1010 out += try std.unicode.utf8Encode(codepoint, buffer[out..]);
1011 } else return error.BadEntity;
1012 }
1013 return buffer[0..out];
1014}