feat: add craft-proto (IMAP4rev1 + SMTP clients) (#1457)

* feat: add craft-proto (IMAP4rev1 + SMTP clients)

Port from mailcraft: IMAP4rev1 and SMTP protocol clients over any
Read + Write stream, no sockets or browser APIs.

## IMAP (RFC 3501, 4315, 4959, 6154, 6851)
- Mailbox operations: SELECT, EXAMINE, LIST, LSUB
- Message operations: FETCH, STORE, COPY, MOVE, EXPUNGE
- IDLE (RFC 2177): server-initiated change notifications
- AUTH: PLAIN, LOGIN, XOAUTH2 (RFC 4954)
- STATUS (RFC 3501 §6.3.10): mailbox stats without opening
- Modified UTF-7 encoding for mailbox names

## SMTP (RFC 5321, 3207, 4954)
- EHLO/HELO, MAIL FROM, RCPT TO, DATA
- STARTTLS (RFC 3207)
- AUTH: PLAIN, LOGIN, XOAUTH2

## Design
- No I/O of its own: works over any Read + Write stream
- Hostile-input bounded reading: lines, literals, counts capped
- Passwords and tokens never reach logs or errors (Secrets wiped on drop)
- Follows craft-libs safety pattern: no unwrap/expect/panic

* fix(proto): restore standalone protocol wiring and safe authentication helpers

* fix(proto): register dependencies and export message macro

* fix(proto): retain upstream private trace filtering and regression coverage

* fix(proto): redact uppercase private reply text and preserve error API

* fix(proto): satisfy hosted workspace lint gates

* fix(proto): bound IDLE polling and preserve mailbox updates safely

* test(proto): exercise BODY sections in FETCH context

* test(proto): distinguish fixed UID ranges from wildcard bounds
This commit is contained in:
Dylan M. Taylor authored and GitHub committed 2026-11-15 04:02:49 -05:00
1 parent 979413980e
commit 26a4f6c855
22 files changed
+6050

No files matched your search

Generated
+10
View File
@@ -2385,6 +2385,16 @@ dependencies = [
"unicode-normalization",
]
[[package]]
name = "craft-proto"
version = "0.1.0"
dependencies = [
"base64 0.23.1",
"log",
"proptest",
"zeroize",
]
[[package]]
name = "craft-ps"
version = "0.1.0"
+1
View File
@@ -12,6 +12,7 @@ repository = "https://github.com/storytold/craft-libs"
[workspace.dependencies]
craft-ber = { path = "crates/ber" }
craft-proto = { path = "crates/proto" }
acadrust = "=0.6.6"
log = "0.4"
# internal: add each crate here as `craft-<name> = { path = "crates/<name>" }`
+20
View File
@@ -0,0 +1,20 @@
[package]
name = "craft-proto"
description = "Mail protocols without sockets: IMAP4rev1 and SMTP clients over any Read + Write stream"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
base64 = "0.23"
zeroize = "1"
# Internationalization: error messages and user-facing text.
log = { workspace = true }
[dev-dependencies]
proptest = { workspace = true }
+246
View File
@@ -0,0 +1,246 @@
// SPDX-FileCopyrightText: Craft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
//! Error message handling for protocol errors.
//!
//! Provides the `said!` macro and related types for creating user-facing error messages.
pub use crate::said;
use std::fmt;
/// A value that can be converted to an argument for error messages.
pub trait ToArg {
fn to_arg(&self) -> Arg;
}
impl<T: fmt::Display> ToArg for T {
fn to_arg(&self) -> Arg {
Arg::Plain(format!("{}", self))
}
}
/// An argument for error messages.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Arg {
Plain(String),
}
impl fmt::Display for Arg {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Arg::Plain(s) => f.write_str(s),
}
}
}
impl Arg {
/// Create an argument from a string.
pub fn said(t: Text) -> Self {
Arg::Plain(format!("{}", t))
}
}
/// A text with values: `said!("no folder named {name}", name)`, or
/// `said!("{name} is larger than {mb} MB", name, mb = MAX >> 20)`.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Text {
template: String,
}
impl Text {
/// Preserve text supplied by a server or host without interpreting it.
pub fn verbatim(text: String) -> Self {
Self { template: text }
}
/// Create a new text with the given template and arguments.
pub fn new(template: &str, args: Vec<(&str, Arg)>) -> Self {
// Substitute only placeholders in the template, never text inserted by a server.
let mut filled = String::new();
let mut rest = template;
while let Some(open) = rest.find('{') {
filled.push_str(rest.get(..open).unwrap_or_default());
let after = rest.get(open.saturating_add(1)..).unwrap_or_default();
let Some(close) = after.find('}') else {
filled.push_str(rest.get(open..).unwrap_or_default());
rest = "";
break;
};
let key = after.get(..close).unwrap_or_default();
if let Some((_, arg)) = args.iter().find(|(name, _)| *name == key) {
filled.push_str(&arg.to_string());
} else {
filled.push('{');
filled.push_str(key);
filled.push('}');
}
rest = after.get(close.saturating_add(1)..).unwrap_or_default();
}
filled.push_str(rest);
Text { template: filled }
}
}
impl fmt::Display for Text {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.template)
}
}
impl From<&str> for Text {
fn from(s: &str) -> Self {
Text { template: s.to_string() }
}
}
impl From<String> for Text {
fn from(s: String) -> Self {
Self::verbatim(s)
}
}
/// The `said!` macro for creating error messages.
#[macro_export]
macro_rules! said {
(@arg $k:ident) => { $crate::i18n::ToArg::to_arg(&$k) };
(@arg $k:ident = $v:expr) => { $crate::i18n::ToArg::to_arg(&$v) };
($t:literal $(, $k:ident $(= $v:expr)?)* $(,)?) => {
$crate::i18n::Text::new($t, vec![$((stringify!($k), $crate::said!(@arg $k $(= $v)?))),*])
};
}
/// Trace only recognized protocol structure, never arbitrary reply text or command arguments.
/// Uppercase text can be private too; capitalization must not determine what is safe to log.
pub fn for_trace(line: &str) -> String {
let line = line.trim_end();
let mut words = line.split_ascii_whitespace();
let first = words.next().unwrap_or_default();
let known = |word: &str| {
matches!(
word,
"OK" | "NO"
| "BAD"
| "BYE"
| "PREAUTH"
| "CAPABILITY"
| "LOGIN"
| "LOGOUT"
| "AUTHENTICATE"
| "SELECT"
| "EXAMINE"
| "CREATE"
| "DELETE"
| "RENAME"
| "SUBSCRIBE"
| "UNSUBSCRIBE"
| "LIST"
| "LSUB"
| "STATUS"
| "APPEND"
| "CHECK"
| "CLOSE"
| "EXPUNGE"
| "SEARCH"
| "FETCH"
| "STORE"
| "COPY"
| "MOVE"
| "UID"
| "IDLE"
| "DONE"
| "NOOP"
| "EHLO"
| "HELO"
| "STARTTLS"
| "AUTH"
| "MAIL"
| "RCPT"
| "DATA"
| "RSET"
| "QUIT"
| "EXISTS"
| "RECENT"
| "FLAGS"
)
};
let smtp_code = first.get(..3).is_some_and(|code| code.bytes().all(|b| b.is_ascii_digit()))
&& first.as_bytes().first().is_some_and(|b| matches!(b, b'1'..=b'5'));
let tag = first.strip_prefix('A').is_some_and(|digits| !digits.is_empty() && digits.len() <= 16 && digits.bytes().all(|b| b.is_ascii_digit()));
let end = if smtp_code && (first.len() == 3 || first.get(3..4) == Some("-")) {
if first.len() > 3 { 4 } else { 3 }
} else if known(first) {
first.len()
} else if first == "*" || tag {
let second = words.next().unwrap_or_default();
let last = if first == "*" && !second.is_empty() && second.bytes().all(|b| b.is_ascii_digit()) {
words.next().filter(|word| known(word))
} else {
known(second).then_some(second)
};
last.and_then(|word| line.find(word)?.checked_add(word.len())).unwrap_or(first.len())
} else if first == "+" {
1
} else {
0
};
let kept = line.get(..end).unwrap_or_default();
let left = line.get(end..).unwrap_or_default().trim_start().len();
match (kept.is_empty(), left) {
(_, 0) => kept.to_owned(),
(true, _) => format!("({left} bytes)"),
(false, _) => format!("{kept} … ({left} bytes)"),
}
}
/// Server text made fit for an error message: one line, no control characters, not too long.
pub fn tidy(text: &str) -> String {
const MAX_CHARS: usize = 300;
let mut out = String::new();
let mut space = false;
for (n, c) in text.trim().chars().enumerate() {
if n >= MAX_CHARS {
out.push('…');
break;
}
if c.is_control() || c.is_whitespace() {
space = !out.is_empty();
} else {
if space {
out.push(' ');
space = false;
}
out.push(c);
}
}
out
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
#[test]
fn inserted_arguments_are_not_interpreted() {
let msg = Text::new("{a} {b}", vec![("a", Arg::Plain("{b}".into())), ("b", Arg::Plain("secret".into()))]);
assert_eq!(msg.to_string(), "{b} secret");
}
#[test]
fn simple_message() {
let msg = said!("the server closed the connection");
assert_eq!(msg.to_string(), "the server closed the connection");
}
#[test]
fn message_with_args() {
let msg = said!("the server sent {n} bytes", n = 123);
assert_eq!(msg.to_string(), "the server sent 123 bytes");
}
#[test]
fn tidy_removes_control_chars() {
assert_eq!(tidy("hello\x01world"), "hello world");
assert_eq!(tidy("hello\nworld"), "hello world");
}
}
+230
View File
@@ -0,0 +1,230 @@
// SPDX-FileCopyrightText: MailCraft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
//! Gmail's labels of a message (`X-GM-LABELS`, Google's "Gmail IMAP extensions", #1153).
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use proptest::prelude::*;
use super::*;
use crate::script::Script;
fn labels(server: &str) -> Vec<(u32, Option<Vec<String>>)> {
let mut s = Script::new(server);
let got = Imap::resume(&mut s).uid_fetch_flags_gmail("1:*").unwrap_or_default();
got.into_iter().map(|f| (f.uid, f.gmail_labels)).collect()
}
fn owned(labels: &[&str]) -> Option<Vec<String>> {
Some(labels.iter().map(|l| l.to_string()).collect())
}
#[test]
fn labels_come_with_the_flags() {
let mut server = String::new();
// Atoms, quoted strings, Gmail's own with their backslash, an empty list.
server += "* 1 FETCH (UID 1 FLAGS (\\Seen) X-GM-MSGID 11 X-GM-LABELS (\\Inbox \\Sent Important \"Muy Importante\"))\r\n";
server += "* 2 FETCH (X-GM-LABELS (foo) UID 2 FLAGS ())\r\n";
server += "* 3 FETCH (UID 3 FLAGS () X-GM-LABELS ())\r\n";
// A literal, and modified UTF-7 as mailbox names are written.
server += "* 4 FETCH (UID 4 FLAGS () X-GM-LABELS ({12}\r\nWork/Clients \"Caf&AOk-\" &AOk-t&AOk-))\r\n";
// UTF-8 as it stands, and an ampersand that isn't the start of a shifted run.
server += "* 5 FETCH (UID 5 FLAGS () X-GM-LABELS (\"Été\" \"Tom & Jerry\" \\Drafts))\r\n";
// A message the server gave none for.
server += "* 6 FETCH (UID 6 FLAGS ())\r\n";
server += "A0001 OK done\r\n";
let mut s = Script::new(server);
let got = Imap::resume(&mut s).uid_fetch_flags_gmail("1:*").unwrap();
assert_eq!(s.sent(), "A0001 UID FETCH 1:* (UID FLAGS X-GM-MSGID X-GM-LABELS)\r\n");
let got: Vec<(u32, Option<Vec<String>>)> = got.into_iter().map(|f| (f.uid, f.gmail_labels)).collect();
assert_eq!(
got,
[
(1, owned(&["\\Inbox", "\\Sent", "Important", "Muy Importante"])),
(2, owned(&["foo"])),
(3, owned(&[])),
(4, owned(&["Work/Clients", "Café", "été"])),
(5, owned(&["Été", "Tom & Jerry", "\\Drafts"])),
(6, None),
]
);
}
#[test]
fn the_later_word_counts_and_other_servers_are_not_asked() {
let got = labels(
"* 1 FETCH (UID 1 FLAGS () X-GM-LABELS (a))\r\n* 1 FETCH (UID 1 X-GM-LABELS (b c))\r\n* 1 FETCH (UID 1 FLAGS ())\r\nA0001 OK done\r\n",
);
assert_eq!(got, [(1, owned(&["b", "c"]))]);
// Without asking for them, labels the server gives anyway are not taken.
let mut s = Script::new("* 1 FETCH (UID 1 FLAGS () X-GM-LABELS (a))\r\nA0001 OK done\r\n");
let plain = Imap::resume(&mut s).uid_fetch_flags("1:*").unwrap();
assert_eq!(plain.first().and_then(|f| f.gmail_labels.clone()), None);
assert_eq!(s.sent(), "A0001 UID FETCH 1:* (UID FLAGS)\r\n");
}
#[test]
fn hostile_label_lists_are_kept_small() {
// A huge list: only so many are kept.
let many: String = (0..1000).map(|n| format!(" L{n}")).collect();
let got = labels(&format!("* 1 FETCH (UID 1 FLAGS () X-GM-LABELS ({many}))\r\nA0001 OK done\r\n"));
assert_eq!(got.first().and_then(|(_, l)| l.as_ref()).map(Vec::len), Some(MAX_GMAIL_LABELS));
// A long label is cut, at a character boundary.
let long = "é".repeat(400);
let got = labels(&format!("* 1 FETCH (UID 1 FLAGS () X-GM-LABELS (\"{long}\"))\r\nA0001 OK done\r\n"));
let label = got.first().and_then(|(_, l)| l.as_ref()).and_then(|l| l.first()).cloned().unwrap_or_default();
assert!(label.len() <= MAX_GMAIL_LABEL_LEN && !label.is_empty() && label.chars().all(|c| c == 'é'));
// A NUL in a literal is carried as text for the model to clean; a list inside the list is
// skipped; a list that isn't closed is read as far as it goes.
let got = labels("* 1 FETCH (UID 1 FLAGS () X-GM-LABELS ({3}\r\na\0b (nested list) ok))\r\nA0001 OK done\r\n");
assert_eq!(got, [(1, owned(&["a\0b", "ok"]))]);
let got = labels("* 1 FETCH (UID 1 FLAGS () X-GM-LABELS (a (b\r\nA0001 OK done\r\n");
assert!(got.len() <= 1);
// Something other than a list is no labels.
let got = labels("* 1 FETCH (UID 1 FLAGS () X-GM-LABELS NIL)\r\nA0001 OK done\r\n");
assert_eq!(got, [(1, None)]);
}
#[test]
fn a_fetch_keeps_no_more_label_bytes_than_its_budget() {
// Labels as literals, which the cap on a command's text doesn't count: each message with as
// many as a response may carry, of 256 bytes each. Past 32 MiB the rest come without.
let label = "x".repeat(MAX_GMAIL_LABEL_LEN);
let list: String = (0..MAX_LITERALS).map(|_| format!(" {{{}}}\r\n{label}", label.len())).collect();
let count = MAX_GMAIL_LABEL_BYTES / (MAX_GMAIL_LABEL_LEN * MAX_LITERALS) + 4;
let mut server = String::new();
for uid in 1..=count {
server += &format!("* {uid} FETCH (UID {uid} FLAGS () X-GM-LABELS ({list}))\r\n");
}
server += "A0001 OK done\r\n";
let mut s = Script::new(server);
let mut imap = Imap::resume(&mut s);
imap.selected = Selected { exists: u32::try_from(count).unwrap_or(u32::MAX), uid_validity: 1, uid_next: 0 };
let got = imap.uid_fetch_flags_gmail("1:*").unwrap();
assert_eq!(got.len(), count);
let kept: usize = got.iter().filter_map(|f| f.gmail_labels.as_ref()).flatten().map(String::len).sum();
assert!(kept <= MAX_GMAIL_LABEL_BYTES);
assert!(got.last().is_some_and(|f| f.gmail_labels.is_none()));
}
proptest! {
#[test]
fn arbitrary_label_lists_never_panic(inside in proptest::collection::vec(any::<u8>(), 0..400)) {
let mut server = b"* 1 FETCH (UID 1 FLAGS () X-GM-LABELS (".to_vec();
server.extend(inside.iter().filter(|b| **b != b'\r' && **b != b'\n'));
server.extend_from_slice(b"))\r\nA0001 OK done\r\n");
let mut s = Script::new(server);
if let Ok(got) = Imap::resume(&mut s).uid_fetch_flags_gmail("1:*") {
for labels in got.iter().filter_map(|f| f.gmail_labels.as_ref()) {
prop_assert!(labels.len() <= MAX_GMAIL_LABELS);
}
}
}
#[test]
fn arbitrary_server_bytes_never_panic_in_a_gmail_fetch(server in proptest::collection::vec(any::<u8>(), 0..600)) {
let mut s = Script::new(server);
let _ = Imap::resume(&mut s).uid_fetch_flags_gmail("1:*");
}
}
#[test]
fn a_folder_other_than_the_inbox_asks_for_labels_alone() {
let mut s = Script::new("* 1 FETCH (UID 1 FLAGS () X-GM-MSGID 5 X-GM-LABELS (a))\r\nA0001 OK done\r\n");
let got = Imap::resume(&mut s).uid_fetch_flags_labels("1:*").unwrap();
assert_eq!(s.sent(), "A0001 UID FETCH 1:* (UID FLAGS X-GM-LABELS)\r\n");
// An id it wasn't asked for is not taken.
assert_eq!(got.into_iter().map(|f| (f.uid, f.gmail_id, f.gmail_labels)).collect::<Vec<_>>(), [(1, None, owned(&["a"]))]);
}
#[test]
fn nil_in_a_list_is_no_label() {
assert_eq!(labels("* 1 FETCH (UID 1 FLAGS () X-GM-LABELS (NIL))\r\nA0001 OK done\r\n"), [(1, owned(&[]))]);
// A label called so comes quoted, and is one.
assert_eq!(labels("* 1 FETCH (UID 1 FLAGS () X-GM-LABELS (nil \"NIL\"))\r\nA0001 OK done\r\n"), [(1, owned(&["NIL"]))]);
}
#[test]
fn tiny_labels_count_against_the_budget_too() {
// Empty labels, as many as a message keeps: each costs its overhead, so the budget still ends.
let list: String = (0..MAX_GMAIL_LABELS).map(|_| " \"\"").collect();
let per_message = MAX_GMAIL_LABELS * LABEL_OVERHEAD;
let count = MAX_GMAIL_LABEL_BYTES / per_message + 4;
let mut server = String::new();
for uid in 1..=count {
server += &format!("* {uid} FETCH (UID {uid} FLAGS () X-GM-LABELS ({list}))\r\n");
}
server += "A0001 OK done\r\n";
let mut s = Script::new(server);
let mut imap = Imap::resume(&mut s);
imap.selected = Selected { exists: u32::try_from(count).unwrap_or(u32::MAX), uid_validity: 1, uid_next: 0 };
let got = imap.uid_fetch_flags_labels("1:*").unwrap();
assert_eq!(got.len(), count);
let kept = got.iter().filter(|f| f.gmail_labels.is_some()).count();
assert!(kept * per_message <= MAX_GMAIL_LABEL_BYTES && kept < count);
}
#[test]
fn a_big_folders_listing_is_not_cut_short_for_its_size() {
// 300,000 messages with labels: more text than one command may otherwise bring (32 MiB).
let count: u32 = 300_000;
let mut server = String::with_capacity(count as usize * 200);
for uid in 1..=count {
server += &format!(
"* {uid} FETCH (FLAGS (\\Seen) UID {uid} X-GM-LABELS (\\Inbox \\Important \"Work/Clients and partners\" \"Receipts 2026\" \"Travel/Japan\"))\r\n"
);
}
assert!(server.len() > MAX_COMMAND_TEXT);
server += "A0001 OK done\r\n";
let mut s = Script::new(server);
let mut imap = Imap::resume(&mut s);
imap.selected = Selected { exists: count, uid_validity: 1, uid_next: count + 1 };
assert_eq!(imap.uid_fetch_flags_labels("1:*").map(|got| got.len()), Ok(count as usize));
// The room is the listing's alone: the next command has the usual cap again.
assert_eq!(imap.text_cap, MAX_COMMAND_TEXT);
}
#[test]
fn a_mailbox_claimed_huge_cant_fill_memory_with_flags() {
// Any server (no Gmail here): ten million messages claimed, then message after message with
// every flag it may have. The text it may send is capped, and so are the flags kept: the
// listing fails, and never hands back messages that seem to have lost their flags.
let flags: Vec<String> = (0..MAX_FLAGS).map(|n| format!("f{n}")).collect();
let flags = flags.join(" ");
let mut server = String::new();
let mut uid = 0u32;
while server.len() < MAX_FETCH_TEXT / 4 {
uid += 1;
server += &format!("* {uid} FETCH (UID {uid} FLAGS ({flags}))\r\n");
}
server += "A0001 OK done\r\n";
let mut s = Script::new(server);
let mut imap = Imap::resume(&mut s);
imap.selected = Selected { exists: 10_000_000, uid_validity: 1, uid_next: 0 };
let got = imap.uid_fetch_flags("1:*");
assert!(matches!(&got, Err(ProtoError::Protocol(m)) if format!("{m:?}").contains("more flags")), "{:?}", got.as_ref().map(Vec::len));
assert_eq!(imap.text_cap, MAX_COMMAND_TEXT);
// And what it may send at all stays within the ceiling, however many messages are claimed.
let mut s = Script::new(format!("* OK {}\r\n", "x".repeat(60_000)).repeat(MAX_FETCH_TEXT / 60_000 + 8));
let mut imap = Imap::resume(&mut s);
imap.selected = Selected { exists: u32::MAX, uid_validity: 1, uid_next: 0 };
assert!(matches!(imap.uid_fetch_flags("1:*"), Err(ProtoError::Protocol(_))));
}
#[test]
fn an_honest_big_mailboxs_flags_fit_the_budget() {
// A million messages with three flags each.
const { assert!(1_000_000 * (ENTRY_OVERHEAD + 3 * (FLAG_OVERHEAD + 8)) <= MAX_FLAG_BYTES) };
}
#[test]
fn a_small_folders_listing_still_has_its_cap() {
// One message, and more than 32 MiB of other lines before it: refused as before.
let junk = format!("* OK {}\r\n", "x".repeat(60_000));
let mut server = junk.repeat(MAX_COMMAND_TEXT / 60_000 + 8);
server += "* 1 FETCH (UID 1 FLAGS () X-GM-LABELS (a))\r\nA0001 OK done\r\n";
let mut s = Script::new(server);
let mut imap = Imap::resume(&mut s);
imap.selected = Selected { exists: 1, uid_validity: 1, uid_next: 2 };
assert!(matches!(imap.uid_fetch_flags_labels("1:*"), Err(ProtoError::Protocol(_))));
assert_eq!(imap.text_cap, MAX_COMMAND_TEXT);
}
+79
View File
@@ -0,0 +1,79 @@
// SPDX-FileCopyrightText: MailCraft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
//! Gmail's IMAP extensions (#911): `X-GM-MSGID` and `X-GM-RAW`.
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
use crate::script::Script;
#[test]
fn gmail_ids_come_with_the_flags() {
let mut server = String::new();
server += "* 1 FETCH (UID 4 FLAGS (\\Seen) X-GM-MSGID 1278455344230334865)\r\n";
server += "* 2 FETCH (X-GM-MSGID 18446744073709551615 UID 7 FLAGS ())\r\n";
// An id that is no number, or 0, is none; a later word about a message without one keeps it.
server += "* 3 FETCH (UID 9 FLAGS () X-GM-MSGID 12ab)\r\n";
server += "* 4 FETCH (UID 10 FLAGS () X-GM-MSGID 0)\r\n";
server += "* 2 FETCH (UID 7 FLAGS (\\Flagged))\r\n";
server += "A0001 OK done\r\n";
let mut s = Script::new(server);
let got = Imap::resume(&mut s).uid_fetch_flags_gmail("1:*").unwrap();
let ids: Vec<(u32, Option<u64>)> = got.iter().map(|f| (f.uid, f.gmail_id)).collect();
assert_eq!(ids, [(4, Some(1_278_455_344_230_334_865)), (7, Some(u64::MAX)), (9, None), (10, None)]);
assert_eq!(got.get(1).map(|f| f.flags.clone()), Some(vec!["\\Flagged".to_string()]));
assert_eq!(s.sent(), "A0001 UID FETCH 1:* (UID FLAGS X-GM-MSGID X-GM-LABELS)\r\n");
// Without asking for them, an id the server gives anyway is not taken.
let mut s = Script::new("* 1 FETCH (UID 4 FLAGS () X-GM-MSGID 5)\r\nA0001 OK done\r\n");
assert_eq!(Imap::resume(&mut s).uid_fetch_flags("1:*").unwrap().first().and_then(|f| f.gmail_id), None);
}
#[test]
fn gmail_search_is_quoted_and_kept_to_its_set() {
let mut s = Script::new("* SEARCH 9 4 0 x 4 12 600\r\nA0001 OK done\r\nA0002 OK done\r\n");
let mut imap = Imap::resume(&mut s);
// In UID order, once each, and only what the set names.
assert_eq!(imap.uid_search_gmail("4:12", "category:social"), Ok(vec![4, 9, 12]));
// Quotes are quoted; CR, LF and NUL never go out.
assert_eq!(imap.uid_search_gmail("1:*", "category:\"x\"\r\nA9 DELETE INBOX\0"), Ok(vec![]));
assert_eq!(
s.sent(),
"A0001 UID SEARCH UID 4:12 UNDELETED X-GM-RAW \"category:social\"\r\n\
A0002 UID SEARCH UID 1:* UNDELETED X-GM-RAW \"category:\\\"x\\\"A9 DELETE INBOX\"\r\n"
);
// A refusal is said.
let mut s = Script::new("A0001 BAD no such search\r\n");
assert!(matches!(Imap::resume(&mut s).uid_search_gmail("1:*", "category:forums"), Err(ProtoError::Rejected(_))));
// What can't be sent is refused unsent.
for (set, query) in [("1:*", ""), ("1:*", "\r\n"), ("1:*", "kategorie:äöü"), ("1 2", "category:social"), ("", "category:social")] {
let mut s = Script::new("A0001 OK done\r\n");
assert!(matches!(Imap::resume(&mut s).uid_search_gmail(set, query), Err(ProtoError::Protocol(_))), "{set:?} {query:?}");
assert_eq!(s.sent(), "", "{set:?} {query:?}");
}
}
#[test]
fn gmail_search_takes_no_more_than_its_cap() {
let many: String = (1..=6000).map(|n| format!(" {n}")).collect();
let mut s = Script::new(format!("* SEARCH{many}\r\nA0001 OK done\r\n"));
assert_eq!(Imap::resume(&mut s).uid_search_gmail("1:*", "category:promotions").map(|uids| uids.len()), Ok(MAX_GMAIL_FOUND));
// As many as the cap, at the longest a UID is written, fit in one line.
let longest: String = (0..MAX_GMAIL_FOUND).map(|_| " 4294967295").collect();
assert!(format!("* SEARCH{longest}").len() < crate::MAX_LINE);
}
#[test]
fn a_gmail_answer_too_long_is_refused_and_the_session_goes_on() {
let long: String = (0..20_000).map(|n| format!(" {}", 1_000_000_000u32 + n)).collect();
assert!(long.len() > crate::MAX_LINE);
let server = format!("* SEARCH{long}\r\n* SEARCH 3\r\nA0001 OK done\r\n* SEARCH 5\r\nA0002 OK done\r\n");
let mut s = Script::new(server);
let mut imap = Imap::resume(&mut s);
assert!(matches!(imap.uid_search_gmail("1:*", "category:social"), Err(ProtoError::Rejected(_))));
// The next command is answered as if nothing had happened.
assert_eq!(imap.uid_search_gmail("1:*", "category:social"), Ok(vec![5]));
// Elsewhere a line that long still ends the session, and a tagged one is never read past.
let mut s = Script::new(format!("* SEARCH{long}\r\nA0001 OK done\r\n"));
assert!(matches!(Imap::resume(&mut s).uid_search_header("Message-ID", "x"), Err(ProtoError::Protocol(_))));
let mut s = Script::new(format!("A0001 OK{long}\r\n"));
assert!(matches!(Imap::resume(&mut s).uid_search_gmail("1:*", "category:social"), Err(ProtoError::Protocol(_))));
}
+185
View File
@@ -0,0 +1,185 @@
// SPDX-FileCopyrightText: MailCraft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
//! IDLE (RFC 2177): the server says when a mailbox changes, instead of being asked. The session
//! is in one of two states, and this module only moves it between them: a mailbox is selected
//! (EXAMINE), [`Imap::idle_begin`] puts the server to waiting, [`Imap::idle_poll`] hears what it
//! says (a line a second at most, so that the caller can look at the clock and at whether it was
//! told to stop), and [`Imap::idle_end`] says DONE and reads on to the command's end.
//!
//! The server's word is bounded as everywhere: a line over [`crate::MAX_LINE`] and a line that
//! announces a literal end the session, and the caller counts what it hears.
use std::io::{Read, Write};
use super::Imap;
use super::parse;
use crate::i18n::{Arg, said};
use crate::{ProtoError, for_trace};
/// Most lines [`Imap::idle_end`] reads on the way to the command's end.
const MAX_ENDING: usize = 256;
/// Most quiet reads [`Imap::idle_end`] waits through for one line.
const MAX_QUIET: usize = 30;
/// What the server said while it was waiting.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum IdleEvent {
/// `* n EXISTS`: the mailbox now has `n` messages.
Exists(u32),
/// `* n EXPUNGE`: the message with that sequence number is gone.
Expunge(u32),
/// `* n RECENT`: `n` messages are new since the mailbox was opened.
Recent(u32),
/// Anything else the server said unasked (a flag change, a status line): not news of mail.
Other,
/// The server ended the command itself (`tag OK`): IDLE has to be begun again.
Ended,
}
/// From the text after `* `: `3 EXISTS`.
fn event_from(rest: &[u8], secrets: &crate::Secrets) -> Result<IdleEvent, ProtoError> {
let text = String::from_utf8_lossy(rest);
let mut words = text.split_whitespace();
let (first, second) = (words.next().unwrap_or(""), words.next().unwrap_or(""));
let count = first.parse::<u32>().ok();
Ok(match (count, second.to_ascii_uppercase().as_str()) {
(Some(n), "EXISTS") => IdleEvent::Exists(n),
(Some(n), "EXPUNGE") => IdleEvent::Expunge(n),
(Some(n), "RECENT") => IdleEvent::Recent(n),
_ if first.eq_ignore_ascii_case("BYE") => {
return Err(ProtoError::Io(said!("the server ended the session: {reason}", reason = crate::tidy(&secrets.hide(&text)))));
}
_ => IdleEvent::Other,
})
}
impl<S: Read + Write> Imap<S> {
/// Send IDLE and wait for the server's go-ahead. The session has to have a mailbox selected;
/// a server that refuses (NO, BAD) is an error. While idle, the only commands that may follow
/// are [`Imap::idle_poll`] and [`Imap::idle_end`].
pub fn idle_begin(&mut self) -> Result<(), ProtoError> {
if self.idle_tag.is_some() {
return Err(ProtoError::Protocol(said!("the server is already idling")));
}
self.idle_pending.clear();
let tag = self.tag();
self.text_seen = 0;
log::trace!("C: {tag} IDLE");
self.wire.write(format!("{tag} IDLE\r\n").as_bytes())?;
self.wire.flush()?;
self.idle_tag = Some(tag.clone());
// Untagged lines may come before the `+`; the tagged answer is a refusal.
for _ in 0..MAX_ENDING {
match self.read_response()? {
super::Response::GoAhead => return Ok(()),
super::Response::Status { tag: Some(answered), line } => {
self.idle_tag = None;
if answered != tag {
return Err(ProtoError::Protocol(said!("the server answered a command that wasn't sent")));
}
return Err(ProtoError::Rejected(self.refusal(&line)));
}
super::Response::Status { tag: None, line } => {
if line.status == parse::Status::Bye {
self.idle_tag = None;
return Err(ProtoError::Io(said!("the server ended the session: {reason}", reason = Arg::said(self.refusal(&line)))));
}
self.note_status(&line);
}
super::Response::Data(values) => {
self.note_data(&values);
let event = match (values.first().and_then(parse::Value::number), values.get(1).and_then(parse::Value::atom)) {
(Some(n), Some(word)) if word.eq_ignore_ascii_case("EXISTS") => IdleEvent::Exists(n),
(Some(n), Some(word)) if word.eq_ignore_ascii_case("EXPUNGE") => IdleEvent::Expunge(n),
(Some(n), Some(word)) if word.eq_ignore_ascii_case("RECENT") => IdleEvent::Recent(n),
_ => IdleEvent::Other,
};
self.idle_pending.push_back(event);
}
}
}
self.idle_tag = None;
Err(ProtoError::Protocol(said!("the server sent too many responses to one command")))
}
/// The next thing the server says while idle, or `None` after one read if the line is
/// incomplete or no bytes arrived (see [`crate::MAX_LINE`] for the bound on a line).
pub fn idle_poll(&mut self) -> Result<Option<IdleEvent>, ProtoError> {
let Some(tag) = self.idle_tag.clone() else {
return Err(ProtoError::Protocol(said!("the server isn't idling")));
};
if let Some(event) = self.idle_pending.pop_front() {
return Ok(Some(event));
}
let Some(line) = self.wire.poll_line()? else { return Ok(None) };
if log::log_enabled!(log::Level::Trace) {
log::trace!("S: {}", for_trace(&self.secrets.hide(&String::from_utf8_lossy(&line))));
}
if let Some(rest) = line.strip_prefix(b"* ") {
// A literal in what is said while idle is nothing a server has a reason to send.
if parse::literal_marker(rest).is_some() {
return Err(ProtoError::Protocol(said!("the server sent data it has no reason to send while idle")));
}
return event_from(rest, &self.secrets).map(Some);
}
let text = String::from_utf8_lossy(&line);
if text.strip_prefix(tag.as_str()).is_some_and(|rest| rest.starts_with(' ')) {
// The server ended IDLE by itself (a timeout of its own, say).
self.idle_tag = None;
let status = text.split_ascii_whitespace().nth(1).and_then(parse::Status::parse);
return match status {
Some(parse::Status::Ok) => Ok(Some(IdleEvent::Ended)),
Some(parse::Status::No | parse::Status::Bad) => Err(ProtoError::Rejected(said!("the server didn't end IDLE properly"))),
_ => Err(ProtoError::Protocol(said!("the server returned an invalid IDLE completion"))),
};
}
Err(ProtoError::Protocol(said!("the server said something that is no news while idle")))
}
/// Say DONE and read what the server still has to say, up to the end of the command. What was
/// said on the way is given back. After this the session is as it was before
/// [`Imap::idle_begin`].
pub fn idle_end(&mut self) -> Result<Vec<IdleEvent>, ProtoError> {
let Some(tag) = self.idle_tag.take() else {
return Err(ProtoError::Protocol(said!("the server isn't idling")));
};
log::trace!("C: DONE");
self.wire.write(b"DONE\r\n")?;
self.wire.flush()?;
let mut events: Vec<_> = self.idle_pending.drain(..).collect();
for _ in 0..MAX_ENDING {
// The server may take a moment to answer: a few polls of the stream's own wait.
let mut polled = None;
for _ in 0..MAX_QUIET {
polled = self.wire.poll_line()?;
if polled.is_some() {
break;
}
}
let Some(line) = polled else { return Err(ProtoError::Io(said!("the server took too long to answer"))) };
if let Some(rest) = line.strip_prefix(b"* ") {
if parse::literal_marker(rest).is_some() {
return Err(ProtoError::Protocol(said!("the server sent data it has no reason to send while idle")));
}
events.push(event_from(rest, &self.secrets)?);
continue;
}
let text = String::from_utf8_lossy(&line);
let mut words = text.splitn(3, ' ');
let (answered, status) = (words.next().unwrap_or(""), words.next().unwrap_or(""));
if answered != tag {
return Err(ProtoError::Protocol(said!("the server answered a command that wasn't sent")));
}
return match parse::Status::parse(status) {
Some(parse::Status::Ok) => Ok(events),
_ => Err(ProtoError::Rejected(said!("the server didn't end IDLE properly"))),
};
}
Err(ProtoError::Protocol(said!("the server sent too many responses to one command")))
}
/// Whether the server said it can do IDLE (upper-cased capability list as last said).
pub fn offers_idle(&self) -> bool {
self.offers("IDLE")
}
}
+139
View File
@@ -0,0 +1,139 @@
// SPDX-FileCopyrightText: MailCraft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use proptest::prelude::*;
use super::*;
use crate::script::Script;
// Polling now yields after each underlying read, including partial lines.
fn next_event(imap: &mut Imap<&mut Script>) -> Result<Option<IdleEvent>, ProtoError> {
for _ in 0..crate::MAX_LINE + 2 {
match imap.idle_poll() {
Ok(None) => continue,
result => return result,
}
}
panic!("script failed to produce an event within its bounded input");
}
#[test]
fn idle_goes_ahead_hears_news_and_ends() {
// The go-ahead is the first line; the rest is heard by polling.
let mut s2 = Script::new("+ idling\r\n* 4 EXISTS\r\n* 1 RECENT\r\n* 2 FETCH (FLAGS (\\Seen))\r\n* 3 EXPUNGE\r\n");
let mut imap2 = Imap::resume(&mut s2);
imap2.idle_begin().unwrap();
assert_eq!(next_event(&mut imap2).unwrap(), Some(IdleEvent::Exists(4)));
assert_eq!(next_event(&mut imap2).unwrap(), Some(IdleEvent::Recent(1)));
assert_eq!(next_event(&mut imap2).unwrap(), Some(IdleEvent::Other));
assert_eq!(next_event(&mut imap2).unwrap(), Some(IdleEvent::Expunge(3)));
assert_eq!(s2.sent(), "A0001 IDLE\r\n");
let mut s3 = Script::new("+ idling\r\n* 5 EXISTS\r\nA0001 OK IDLE terminated\r\n");
let mut imap3 = Imap::resume(&mut s3);
imap3.idle_begin().unwrap();
assert_eq!(imap3.idle_end().unwrap(), vec![IdleEvent::Exists(5)]);
assert_eq!(s3.sent(), "A0001 IDLE\r\nDONE\r\n");
}
#[test]
fn a_refusal_or_an_early_end_or_a_goodbye_is_said() {
let mut s = Script::new("A0001 NO [CANNOT] not now\r\n");
assert!(matches!(Imap::resume(&mut s).idle_begin(), Err(ProtoError::Rejected(_))));
let mut s = Script::new("+ idling\r\nA0001 OK the server gave up waiting\r\n");
let mut imap = Imap::resume(&mut s);
imap.idle_begin().unwrap();
assert_eq!(next_event(&mut imap).unwrap(), Some(IdleEvent::Ended));
// Not idling any more: nothing to poll or to end.
assert!(matches!(next_event(&mut imap), Err(ProtoError::Protocol(_))));
assert!(matches!(imap.idle_end(), Err(ProtoError::Protocol(_))));
let mut s = Script::new("+ idling\r\n* BYE going away\r\n");
let mut imap = Imap::resume(&mut s);
imap.idle_begin().unwrap();
assert!(matches!(next_event(&mut imap), Err(ProtoError::Io(_))));
}
#[test]
fn what_a_server_has_no_reason_to_send_while_idle_ends_the_session() {
for hostile in ["* 1 FETCH (BODY[] {5}\r\n", "A0099 OK that was never asked\r\n", "garbage\r\n", "* 1 EXISTS\r\n".repeat(0).as_str()] {
let mut s = Script::new(format!("+ idling\r\n{hostile}"));
let mut imap = Imap::resume(&mut s);
imap.idle_begin().unwrap();
let got = next_event(&mut imap);
assert!(got.is_err() || hostile.is_empty(), "{hostile:?}: {got:?}");
}
// A line longer than any a server is allowed.
let mut long = b"+ idling\r\n* ".to_vec();
long.extend(std::iter::repeat_n(b'x', crate::MAX_LINE + 10));
long.extend_from_slice(b"\r\n");
let mut s = Script::whole(long);
let mut imap = Imap::resume(&mut s);
imap.idle_begin().unwrap();
assert!(matches!(next_event(&mut imap), Err(ProtoError::Protocol(_))));
}
proptest! {
#[test]
fn arbitrary_server_bytes_never_panic_while_idle(server in proptest::collection::vec(any::<u8>(), 0..800), greeted in any::<bool>()) {
let mut bytes = if greeted { b"+ idling\r\n".to_vec() } else { Vec::new() };
bytes.extend_from_slice(&server);
let mut s = Script::new(&bytes);
let mut imap = Imap::resume(&mut s);
if imap.idle_begin().is_ok() {
// However much is said, polling ends (the script runs out) and nothing is kept without bound.
for _ in 0..2_000 {
match next_event(&mut imap) {
Ok(Some(_)) => {}
Ok(None) | Err(_) => break,
}
}
let _ = imap.idle_end();
}
}
#[test]
fn idle_shaped_noise_never_panics(words in proptest::collection::vec(proptest::sample::select(&["* ", "1 ", "EXISTS", "EXPUNGE", "RECENT", " ", "\r\n", "A0001 OK ", "BYE ", "{9}", "FETCH (", ")"][..]), 0..60)) {
let mut s = Script::new(format!("+ go\r\n{}", words.concat()));
let mut imap = Imap::resume(&mut s);
if imap.idle_begin().is_ok() {
for _ in 0..200 {
if !matches!(next_event(&mut imap), Ok(Some(_))) {
break;
}
}
let _ = imap.idle_end();
}
}
}
#[test]
fn notifications_before_continuation_are_delivered() {
let mut s = Script::new("* 4 EXISTS\r\n* 2 EXPUNGE\r\n+ idling\r\nA0001 OK done\r\n");
let mut imap = Imap::resume(&mut s);
imap.idle_begin().unwrap();
assert_eq!(imap.idle_poll().unwrap(), Some(IdleEvent::Exists(4)));
assert_eq!(imap.idle_end().unwrap(), vec![IdleEvent::Expunge(2)]);
}
#[test]
fn idle_bye_errors_hide_registered_secrets() {
for ending in [false, true] {
let mut s = Script::new("+ idling\r\n* BYE test-token\r\n");
let mut imap = Imap::resume(&mut s);
imap.secrets.add("test-token");
imap.idle_begin().unwrap();
let error = if ending { imap.idle_end().unwrap_err() } else { next_event(&mut imap).unwrap_err() };
assert!(!error.to_string().contains("test-token"));
}
}
#[test]
fn idle_completion_requires_a_valid_success_status() {
for (status, rejected) in [("NO", true), ("BAD", true), ("nonsense", false)] {
let mut s = Script::new(format!("+ idling\r\nA0001 {status} failed\r\n"));
let mut imap = Imap::resume(&mut s);
imap.idle_begin().unwrap();
let error = next_event(&mut imap).unwrap_err();
assert!(if rejected { matches!(error, ProtoError::Rejected(_)) } else { matches!(error, ProtoError::Protocol(_)) });
}
}
+215
View File
@@ -0,0 +1,215 @@
// SPDX-FileCopyrightText: MailCraft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
//! What one command may make the client keep or read, however much the server sends.
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use proptest::prelude::*;
use super::*;
use crate::script::Script;
/// A session whose open mailbox has `exists` messages and the next UID `uid_next`.
fn opened(s: &mut Script, exists: u32, uid_next: u32) -> Imap<&mut Script> {
let mut imap = Imap::resume(s);
imap.selected = Selected { exists, uid_validity: 1, uid_next };
imap
}
/// `lines` lines made by `line(n)`.
fn flood(lines: usize, line: impl Fn(usize) -> String) -> String {
(0..lines).map(line).collect()
}
fn padding() -> String {
"x".repeat(60 * 1024)
}
#[test]
fn a_flood_of_long_lines_ends_the_command() {
let pad = padding();
// 600 lines of 60 KB are more than the 32 MB one command may bring.
let server = flood(600, |n| format!("* {n} FETCH (UID {} FLAGS ({pad}))\r\n", n + 1)) + "A0001 OK done\r\n";
let mut s = Script::new(server);
let err = opened(&mut s, 1000, 2000).uid_fetch_flags("1:*").unwrap_err();
assert!(matches!(err, ProtoError::Protocol(ref m) if m.to_string().contains("too much")), "{err:?}");
// The same in a list.
let server = flood(600, |n| format!("* LIST () \"/\" \"{n}{pad}\"\r\n")) + "A0001 OK done\r\n";
let mut s = Script::new(server);
assert!(matches!(opened(&mut s, 0, 0).list(), Err(ProtoError::Protocol(_))));
}
#[test]
fn a_flood_of_responses_ends_the_command() {
let server = "* OK still here\r\n".repeat(MAX_RESPONSES + 1) + "A0001 OK done\r\n";
let mut s = Script::new(server);
let err = opened(&mut s, 0, 0).uid_fetch_sizes("1:*").unwrap_err();
assert!(matches!(err, ProtoError::Protocol(ref m) if m.to_string().contains("too many")), "{err:?}");
}
#[test]
fn a_list_keeps_a_capped_number_of_mailboxes() {
let server = flood(MAX_MAILBOXES + 500, |n| format!("* LIST () \"/\" f{n}\r\n")) + "A0001 OK done\r\n";
let mut s = Script::new(server);
let got = opened(&mut s, 0, 0).list().unwrap();
assert_eq!(got.len(), MAX_MAILBOXES);
assert_eq!(got.first().map(|m| m.raw.as_str()), Some("f0"));
// #991: and how many were dropped is said; none, for a list kept whole.
let server = flood(MAX_MAILBOXES + 500, |n| format!("* LIST () \"/\" f{n}\r\n")) + "A0001 OK done\r\n";
let mut s = Script::new(server);
assert_eq!(opened(&mut s, 0, 0).list_counted().unwrap().1, 500);
let mut s = Script::new("* LIST () \"/\" a\r\n* LIST () \"/\" a\r\nA0001 OK done\r\n");
assert_eq!(
opened(&mut s, 0, 0).list_counted().unwrap(),
(vec![Mailbox { name: "a".into(), raw: "a".into(), delimiter: Some('/'), flags: Vec::new() }], 0)
);
}
/// #991: a list keeps a bounded number of bytes too, however many mailboxes that is.
#[test]
fn a_list_keeps_a_capped_number_of_bytes() {
let flags: Vec<String> = (0..MAX_FLAGS).map(|n| format!("\\F{n}{}", "x".repeat(MAX_FLAG_LEN - 8))).collect();
let flags = flags.join(" ");
let server = flood(1_500, |n| format!("* LIST ({flags}) \"/\" f{n}\r\n")) + "A0001 OK done\r\n";
let mut s = Script::new(server);
let (got, dropped) = opened(&mut s, 0, 0).list_counted().unwrap();
assert_eq!(got.len() + dropped, 1_500);
let kept: usize = got.iter().map(|m| m.raw.len() * 2 + m.name.len() + m.flags.iter().map(String::len).sum::<usize>()).sum();
assert!(!got.is_empty() && got.len() < 1_500, "{}", got.len());
// The last one kept may take it over by one mailbox's worth, never more.
assert!(kept < MAX_LIST_BYTES + MAX_LINE, "{kept}");
}
#[test]
fn names_and_flags_are_kept_short() {
let long_flag = "é".repeat(400);
let long_name = "n".repeat(MAX_MAILBOX_NAME + 1);
let server = format!("* LIST ({long_flag} \\Sent) \"/\" Fine\r\n* LIST () \"/\" {long_name}\r\nA0001 OK done\r\n");
let mut s = Script::new(server);
let got = opened(&mut s, 0, 0).list().unwrap();
// The mailbox with the oversized name is left out, not cut into another one.
assert_eq!(got.len(), 1);
assert!(got[0].flags[0].len() <= MAX_FLAG_LEN && got[0].flags[0].chars().all(|c| c == 'é'));
assert_eq!(got[0].flags[1], "\\Sent");
let server = format!("* 1 FETCH (UID 1 FLAGS ({long_flag}))\r\nA0001 OK done\r\n");
let mut s = Script::new(server);
let got = opened(&mut s, 1, 2).uid_fetch_flags("1:*").unwrap();
assert!(got[0].flags[0].len() <= MAX_FLAG_LEN);
}
#[test]
fn only_uids_that_were_asked_for_and_exist_are_kept() {
let server = "* 1 FETCH (UID 3 FLAGS (\\Seen))\r\n* 2 FETCH (UID 7 FLAGS ())\r\n* 3 FETCH (UID 9 FLAGS ())\r\n* 4 FETCH (UID 4000000000 FLAGS ())\r\n\
* 5 FETCH (UID 10 FLAGS ())\r\nA0001 OK done\r\n";
// Not in the set.
let mut s = Script::new(server);
let got = opened(&mut s, 5, 11).uid_fetch_flags("3,8:9").unwrap();
assert_eq!(got.iter().map(|f| f.uid).collect::<Vec<_>>(), [3, 9]);
// UIDNEXT is only a snapshot: later deliveries must not be discarded.
let sizes = server.replace("FLAGS (\\Seen)", "RFC822.SIZE 5").replace("FLAGS ()", "RFC822.SIZE 6");
let mut s = Script::new(sizes);
let got = opened(&mut s, 5, 10).uid_fetch_sizes("1:*").unwrap();
assert_eq!(got, [(3, 5), (7, 6), (9, 6), (10, 6), (4000000000, 6)]);
}
#[test]
fn more_distinct_uids_than_the_mailbox_can_hold_fail_the_command() {
// 3 messages: room for 2 * 3 + FETCH_SLACK distinct UIDs, and not one more.
let room = 2 * 3 + FETCH_SLACK;
let many = |n: usize| flood(n, |i| format!("* {i} FETCH (UID {} FLAGS ())\r\n", i + 1)) + "A0001 OK done\r\n";
let mut s = Script::new(many(room));
assert_eq!(opened(&mut s, 3, u32::MAX).uid_fetch_flags("1:*").unwrap().len(), room);
let mut s = Script::new(many(room + 1));
assert!(matches!(opened(&mut s, 3, u32::MAX).uid_fetch_flags("1:*"), Err(ProtoError::Protocol(_))));
let sizes = flood(room + 1, |i| format!("* {i} FETCH (UID {} RFC822.SIZE 1)\r\n", i + 1)) + "A0001 OK done\r\n";
let mut s = Script::new(sizes);
assert!(matches!(opened(&mut s, 3, u32::MAX).uid_fetch_sizes("1:*"), Err(ProtoError::Protocol(_))));
// The same UID again and again is one.
let same = flood(room * 3, |_| "* 1 FETCH (UID 1 FLAGS ())\r\n".to_string()) + "A0001 OK done\r\n";
let mut s = Script::new(same);
assert_eq!(opened(&mut s, 3, 100).uid_fetch_flags("1:*").unwrap().len(), 1);
}
#[test]
fn set_ranges_read_what_is_written() {
assert_eq!(set_ranges("1:*", 9), Some(vec![(1, 9)]));
assert_eq!(set_ranges("5,9,20:12", 9), Some(vec![(5, 5), (9, 9), (12, 20)]));
assert_eq!(set_ranges("1:x", 9), None);
assert_eq!(set_ranges("", 9), None);
}
proptest! {
/// Whatever the server sends, the command ends, and what it keeps is bounded by the caps.
#[test]
fn arbitrary_responses_are_kept_within_bounds(lines in proptest::collection::vec(("[ -~]{0,200}", any::<u32>(), 0usize..4), 0..400)) {
let server: String = lines
.iter()
.map(|(text, uid, kind)| match kind {
0 => format!("* LIST (\\{text}) \"/\" {text}\r\n"),
1 => format!("* 1 FETCH (UID {uid} FLAGS ({text}))\r\n"),
2 => format!("* 1 FETCH (UID {uid} RFC822.SIZE {uid})\r\n"),
_ => format!("* {text}\r\n"),
})
.collect::<String>()
+ "A0001 OK done\r\n";
let mut s = Script::new(server.clone());
if let Ok(list) = opened(&mut s, 10, 50).list() {
prop_assert!(list.len() <= MAX_MAILBOXES);
prop_assert!(list.iter().all(|m| m.raw.len() <= MAX_MAILBOX_NAME && m.flags.len() <= MAX_FLAGS && m.flags.iter().all(|f| f.len() <= MAX_FLAG_LEN)));
}
let mut s = Script::new(server.clone());
// A fixed range retains its UID bound even if the server sends newer deliveries.
if let Ok(got) = opened(&mut s, 10, 50).uid_fetch_flags("1:49") {
prop_assert!(got.len() <= 2 * 10 + FETCH_SLACK);
prop_assert!(got.iter().all(|f| f.uid >= 1 && f.uid < 50 && f.flags.len() <= MAX_FLAGS && f.flags.iter().all(|x| x.len() <= MAX_FLAG_LEN)));
}
let mut s = Script::new(server.clone());
// Wildcards admit deliveries newer than SELECT's UIDNEXT, but retain all storage caps.
if let Ok(got) = opened(&mut s, 10, 50).uid_fetch_flags("1:*") {
prop_assert!(got.len() <= 2 * 10 + FETCH_SLACK);
prop_assert!(got.iter().all(|f| f.uid >= 1 && f.flags.len() <= MAX_FLAGS && f.flags.iter().all(|x| x.len() <= MAX_FLAG_LEN)));
}
let mut s = Script::new(server);
if let Ok(got) = opened(&mut s, 10, 50).uid_fetch_sizes("5:20") {
prop_assert!(got.iter().all(|(uid, _)| (5..=20).contains(uid)));
}
}
}
#[test]
fn a_folder_with_more_messages_than_other_commands_may_answer_still_reads() {
let exists = 300_000u32;
let lines = |n: u32| flood(n as usize, |i| format!("* {i} FETCH (UID {} FLAGS ())\r\n", i + 1)) + "A0001 OK done\r\n";
let mut s = Script::new(lines(exists));
assert_eq!(opened(&mut s, exists, exists + 1).uid_fetch_flags("1:*").unwrap().len(), exists as usize);
let sizes = flood(exists as usize, |i| format!("* {i} FETCH (UID {} RFC822.SIZE 1)\r\n", i + 1)) + "A0001 OK done\r\n";
let mut s = Script::new(sizes);
assert_eq!(opened(&mut s, exists, exists + 1).uid_fetch_sizes("1:*").unwrap().len(), exists as usize);
// Responses that are not messages still end at the cap for that folder, and the next command is back to the usual one.
let noise = "* OK still here\r\n".repeat(2 * exists as usize + FETCH_SLACK + 1) + "A0001 OK done\r\n";
let mut s = Script::new(noise);
let mut imap = opened(&mut s, exists, exists + 1);
assert!(matches!(imap.uid_fetch_flags("1:*"), Err(ProtoError::Protocol(_))));
assert_eq!(imap.response_cap, MAX_RESPONSES);
}
#[test]
fn short_flags_release_large_backing_allocations() {
let flags = short_flags(vec![Value::Atom("A".repeat(1024 * 1024))]);
assert_eq!(flags[0].len(), MAX_FLAG_LEN);
assert!(flags[0].capacity() <= MAX_FLAG_LEN);
}
#[test]
fn wildcard_fetch_accepts_deliveries_after_select() {
let server = "* 1 FETCH (UID 10 FLAGS ())\r\nA0001 OK done\r\n";
let mut s = Script::new(server);
assert_eq!(opened(&mut s, 1, 10).uid_fetch_flags("*").unwrap()[0].uid, 10);
}
#[test]
fn brackets_in_flag_keywords_do_not_consume_body_sections() {
for flag in ["x[", "BODY["] {
let mut s = Script::new(format!("* 1 FETCH (UID 3 FLAGS ({flag}) BODY[] {{2}}\r\nok)\r\nA0001 OK done\r\n"));
assert_eq!(opened(&mut s, 1, 4).uid_fetch_message(3).unwrap().unwrap().body, Some(b"ok".to_vec()));
}
}
File diff suppressed because it is too large. Load diff
+346
View File
@@ -0,0 +1,346 @@
// SPDX-FileCopyrightText: MailCraft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
//! Reading IMAP responses: the pieces a response arrives in, the values in it, and status lines.
use crate::ProtoError;
use crate::i18n::said;
/// Deepest that parenthesised lists may nest.
const MAX_DEPTH: usize = 32;
/// A response as it came off the wire: lines of text with the literals between them.
#[derive(Debug)]
pub(crate) enum Piece {
Text(Vec<u8>),
Literal(Vec<u8>),
}
/// One value of a response.
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) enum Value {
/// A bare word: a number, a flag, `NIL`, `BODY[]`.
Atom(String),
/// A quoted string or a literal.
Str(Vec<u8>),
List(Vec<Value>),
}
impl Value {
pub(crate) fn atom(&self) -> Option<&str> {
match self {
Value::Atom(a) => Some(a),
_ => None,
}
}
pub(crate) fn number(&self) -> Option<u32> {
self.atom()?.parse().ok()
}
/// The text of a string or a bare word (what the grammar calls an `astring`).
pub(crate) fn into_text(self) -> Option<String> {
match self {
Value::Atom(a) => Some(a),
Value::Str(bytes) => Some(String::from_utf8_lossy(&bytes).into_owned()),
Value::List(_) => None,
}
}
}
/// Where a line ends in a literal marker (`{123}`, also `{123+}`) outside any quoted string: the
/// marker's position and the size it names.
pub(crate) fn literal_marker(line: &[u8]) -> Option<(usize, u64)> {
let inner_end = line.len().checked_sub(1).filter(|last| line.get(*last) == Some(&b'}'))?;
let open = line.iter().rposition(|b| *b == b'{')?;
let inner = line.get(open + 1..inner_end)?;
let digits = inner.strip_suffix(b"+").unwrap_or(inner);
if digits.is_empty() || !digits.iter().all(u8::is_ascii_digit) {
return None;
}
// A brace inside a quoted string is just text.
let (mut quoted, mut escaped) = (false, false);
for b in line.get(..open)? {
if escaped {
escaped = false;
} else if quoted && *b == b'\\' {
escaped = true;
} else if *b == b'"' {
quoted = !quoted;
}
}
if quoted {
return None;
}
// A size beyond u64 is as large as can be, and refused like any other that is too large.
let size = digits.iter().try_fold(0u64, |n, d| n.checked_mul(10)?.checked_add(u64::from(d.wrapping_sub(b'0')))).unwrap_or(u64::MAX);
Some((open, size))
}
/// The values of a response. Unbalanced parentheses are forgiven; lists nested too deeply are not.
pub(crate) fn values(pieces: Vec<Piece>) -> Result<Vec<Value>, ProtoError> {
// The list being filled is on top; the response itself is at the bottom.
let mut stack: Vec<Vec<Value>> = vec![Vec::new()];
let mut pieces = pieces.into_iter().peekable();
while let Some(piece) = pieces.next() {
match piece {
Piece::Literal(bytes) => push(&mut stack, Value::Str(bytes)),
Piece::Text(text) => {
// The marker of the literal that follows is not a value.
let end = match (pieces.peek(), literal_marker(&text)) {
(Some(Piece::Literal(_)), Some((at, _))) => at,
_ => text.len(),
};
scan(text.get(..end).unwrap_or(&[]), &mut stack)?;
}
}
}
while stack.len() > 1 {
close(&mut stack);
}
Ok(stack.pop().unwrap_or_default())
}
fn push(stack: &mut [Vec<Value>], value: Value) {
if let Some(top) = stack.last_mut() {
top.push(value);
}
}
fn close(stack: &mut Vec<Vec<Value>>) {
if stack.len() > 1
&& let Some(list) = stack.pop()
{
push(stack, Value::List(list));
}
}
fn scan(text: &[u8], stack: &mut Vec<Vec<Value>>) -> Result<(), ProtoError> {
// A `[` only opens a section (`BODY[HEADER.FIELDS (TO)]`) when a `]` follows somewhere.
let last_close = text.iter().rposition(|b| *b == b']');
let mut i = 0;
// Every arm moves `i` forward.
while let Some(&b) = text.get(i) {
match b {
b' ' | b'\t' => i += 1,
b'(' => {
if stack.len() > MAX_DEPTH {
return Err(ProtoError::Protocol(said!("the server's response is nested too deeply")));
}
stack.push(Vec::new());
i += 1;
}
b')' => {
close(stack);
i += 1;
}
b'"' => {
let (string, next) = quoted(text, i + 1);
push(stack, Value::Str(string));
i = next;
}
_ => {
let fetch_attribute = stack.len() == 2
&& stack.first().and_then(|root| root.get(1)).and_then(Value::atom).is_some_and(|word| word.eq_ignore_ascii_case("FETCH"));
let end = atom_end(text, i, if fetch_attribute { last_close } else { None });
push(stack, Value::Atom(String::from_utf8_lossy(text.get(i..end).unwrap_or(&[])).into_owned()));
i = end;
}
}
}
Ok(())
}
/// The contents of the quoted string that starts at `start` (after its opening quote), and where
/// the text goes on. A string the line ends in the middle of is taken as far as it goes.
fn quoted(text: &[u8], start: usize) -> (Vec<u8>, usize) {
let mut out = Vec::new();
let mut i = start;
while let Some(&b) = text.get(i) {
match b {
b'"' => return (out, i + 1),
b'\\' => {
out.extend(text.get(i + 1));
i += 2;
}
_ => {
out.push(b);
i += 1;
}
}
}
(out, i)
}
/// Where the bare word starting at `start` ends: at a space or parenthesis outside `[…]`.
fn atom_end(text: &[u8], start: usize, last_close: Option<usize>) -> usize {
let mut i = start;
while let Some(&b) = text.get(i) {
match b {
b' ' | b'\t' | b'(' | b')' if i > start => break,
b'[' if last_close.is_some_and(|close| close > i)
&& text.get(start..i).is_some_and(|prefix| prefix.eq_ignore_ascii_case(b"BODY") || prefix.eq_ignore_ascii_case(b"BODY.PEEK")) =>
{
let close = text.get(i..).and_then(|rest| rest.iter().position(|b| *b == b']')).unwrap_or(0);
i += close + 1;
}
_ => i += 1,
}
}
i
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum Status {
Ok,
No,
Bad,
Bye,
Preauth,
}
impl Status {
pub(crate) fn parse(word: &str) -> Option<Status> {
match word.to_ascii_uppercase().as_str() {
"OK" => Some(Status::Ok),
"NO" => Some(Status::No),
"BAD" => Some(Status::Bad),
"BYE" => Some(Status::Bye),
"PREAUTH" => Some(Status::Preauth),
_ => None,
}
}
}
/// `OK [UIDVALIDITY 3857529045] UIDs valid`, tagged or not.
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) struct StatusLine {
pub(crate) status: Status,
/// The name of the response code, upper-cased (`UIDVALIDITY`); empty when there is none.
pub(crate) code: String,
/// What follows the name inside the brackets.
pub(crate) arg: String,
/// Everything after the status word, code included.
pub(crate) text: String,
}
impl StatusLine {
pub(crate) fn new(status: Status, rest: &str) -> StatusLine {
let text = rest.trim();
let inner = text.strip_prefix('[').and_then(|r| r.split_once(']')).map_or("", |(inner, _)| inner.trim());
let (code, arg) = inner.split_once(' ').unwrap_or((inner, ""));
StatusLine { status, code: code.to_ascii_uppercase(), arg: arg.trim().to_string(), text: text.to_string() }
}
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
fn text(s: &str) -> Piece {
Piece::Text(s.as_bytes().to_vec())
}
fn atom(s: &str) -> Value {
Value::Atom(s.into())
}
fn string(s: &str) -> Value {
Value::Str(s.as_bytes().to_vec())
}
fn parse(s: &str) -> Vec<Value> {
values(vec![text(s)]).unwrap()
}
#[test]
fn atoms_strings_and_lists() {
assert_eq!(
parse(r#"LIST (\HasNoChildren \Sent) "/" "Sent \"old\" \\ mail""#),
vec![atom("LIST"), Value::List(vec![atom("\\HasNoChildren"), atom("\\Sent")]), string("/"), string("Sent \"old\" \\ mail")]
);
assert_eq!(
parse("12 FETCH (UID 7 FLAGS ())"),
vec![atom("12"), atom("FETCH"), Value::List(vec![atom("UID"), atom("7"), atom("FLAGS"), Value::List(vec![])])]
);
assert_eq!(
parse("a ((b) (c (d))) NIL"),
vec![atom("a"), Value::List(vec![Value::List(vec![atom("b")]), Value::List(vec![atom("c"), Value::List(vec![atom("d")])])]), atom("NIL")]
);
assert_eq!(parse(""), vec![]);
assert_eq!(parse(" "), vec![]);
}
#[test]
fn sections_are_part_of_the_word() {
assert_eq!(
parse("12 FETCH (BODY[HEADER.FIELDS (FROM TO)] x BODY[]<0> y)"),
vec![atom("12"), atom("FETCH"), Value::List(vec![atom("BODY[HEADER.FIELDS (FROM TO)]"), atom("x"), atom("BODY[]<0>"), atom("y")])]
);
assert_eq!(parse(r#"LIST () "/" [Gmail]/Trash"#), vec![atom("LIST"), Value::List(vec![]), string("/"), atom("[Gmail]/Trash")]);
// A bracket that never closes is an ordinary character.
assert_eq!(parse("(a[b c)"), vec![Value::List(vec![atom("a[b"), atom("c")])]);
assert_eq!(parse("[[[[ x"), vec![atom("[[[["), atom("x")]);
}
#[test]
fn broken_text_is_read_as_far_as_it_goes() {
assert_eq!(parse("(a (b"), vec![Value::List(vec![atom("a"), Value::List(vec![atom("b")])])]);
assert_eq!(parse("a) b))"), vec![atom("a"), atom("b")]);
assert_eq!(parse(r#""never closed"#), vec![string("never closed")]);
assert_eq!(parse(r#""ends in a backslash\"#), vec![string("ends in a backslash")]);
assert_eq!(parse("a\"b c"), vec![atom("a\"b"), atom("c")]);
let deep = "(".repeat(MAX_DEPTH + 5);
assert!(matches!(values(vec![text(&deep)]), Err(ProtoError::Protocol(_))));
assert!(values(vec![text(&"(".repeat(MAX_DEPTH))]).is_ok());
}
#[test]
fn literals_take_the_place_of_their_marker() {
let pieces =
vec![text("1 FETCH (BODY[] {5}"), Piece::Literal(b"a (\"b".to_vec()), text(" UID 3 X {0}"), Piece::Literal(Vec::new()), text(")")];
assert_eq!(
values(pieces).unwrap(),
vec![atom("1"), atom("FETCH"), Value::List(vec![atom("BODY[]"), string("a (\"b"), atom("UID"), atom("3"), atom("X"), string("")])]
);
// Without a literal after it, a marker is only a word.
assert_eq!(parse("a {5}"), vec![atom("a"), atom("{5}")]);
}
#[test]
fn markers() {
assert_eq!(literal_marker(b"* 1 FETCH (BODY[] {123}"), Some((18, 123)));
assert_eq!(literal_marker(b"{0}"), Some((0, 0)));
assert_eq!(literal_marker(b"x {7+}"), Some((2, 7)));
assert_eq!(literal_marker(b"\"quoted\" {7}"), Some((9, 7)));
assert_eq!(literal_marker(b"x {99999999999999999999999}"), Some((2, u64::MAX)));
for not in ["", "}", "{}", "{+}", "{5} ", "{-5}", "{5 }", "\"in a string {5}", "\"a \\\" {5}", "{5}x", "{ 5}", "5}"] {
assert_eq!(literal_marker(not.as_bytes()), None, "{not:?}");
}
}
#[test]
fn status_lines() {
let s = StatusLine::new(Status::Ok, " [UIDVALIDITY 3857529045] UIDs valid ");
assert_eq!((s.code.as_str(), s.arg.as_str(), s.text.as_str()), ("UIDVALIDITY", "3857529045", "[UIDVALIDITY 3857529045] UIDs valid"));
let s = StatusLine::new(Status::No, "[alert] disk full");
assert_eq!((s.code.as_str(), s.arg.as_str()), ("ALERT", ""));
let s = StatusLine::new(Status::Ok, "done [not a code]");
assert_eq!((s.code.as_str(), s.text.as_str()), ("", "done [not a code]"));
assert_eq!(StatusLine::new(Status::Bad, "[unclosed").code, "");
assert_eq!(StatusLine::new(Status::Bad, "").text, "");
assert_eq!(Status::parse("preauth"), Some(Status::Preauth));
assert_eq!(Status::parse("FETCH"), None);
}
#[test]
fn values_as_numbers_and_text() {
assert_eq!(atom("42").number(), Some(42));
assert_eq!(atom("4294967296").number(), None);
assert_eq!(atom("-1").number(), None);
assert_eq!(string("42").number(), None);
assert_eq!(string("Entw&APw-rfe").into_text().as_deref(), Some("Entw&APw-rfe"));
assert_eq!(Value::Str(vec![0xFF, b'a']).into_text().as_deref(), Some("\u{FFFD}a"));
assert_eq!(Value::List(vec![]).into_text(), None);
}
}
+72
View File
@@ -0,0 +1,72 @@
// SPDX-FileCopyrightText: MailCraft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
//! Password authentication from RFC 4616 and RFC 4959, over an already secured stream.
use super::{Imap, ProtoError, Read, Status, Write, ignore, said};
use base64::{Engine as _, engine::general_purpose::STANDARD};
impl<S: Read + Write> Imap<S> {
/// Prefer the server's advertised PLAIN mechanism; otherwise use LOGIN. The host must
/// secure the stream first. Unknown capabilities are queried here; known ones are reused.
/// A refusal never triggers a second attempt with another mechanism.
pub fn authenticate_password(&mut self, user: &str, password: &str) -> Result<(), ProtoError> {
if password.is_empty() {
return Err(ProtoError::Auth(said!("enter a password to sign in")));
}
if user.is_empty() {
return Err(ProtoError::Auth(said!("enter a user name to sign in")));
}
if self.capabilities.is_none() {
self.capabilities()?;
}
if !self.offers("AUTH=PLAIN") {
return self.login(user, password);
}
if user.contains('\0') || password.contains('\0') {
return Err(ProtoError::Auth(said!("PLAIN needs a user name and password without NUL characters")));
}
if user.len().saturating_add(password.len()) > 32 * 1024 {
return Err(ProtoError::Auth(said!("the user name or password is too long")));
}
// Empty authorization identity: the server derives it from the authentication identity.
let response = STANDARD.encode(format!("\0{user}\0{password}").as_bytes());
self.secrets.add(password);
self.secrets.add(&response);
let inline = self.offers("SASL-IR");
let tag = self.tag();
let command = if inline { format!("{tag} AUTHENTICATE PLAIN {response}\r\n") } else { format!("{tag} AUTHENTICATE PLAIN\r\n") };
log::trace!("C: {tag} AUTHENTICATE PLAIN{}", if inline { " ***" } else { "" });
self.wire.write(command.as_bytes())?;
self.wire.flush()?;
let mut sent = inline;
let mut cancelled = false;
let verdict = loop {
if let Some(verdict) = self.read_until(&tag, true, &mut ignore)? {
break verdict;
}
if cancelled {
return Err(ProtoError::Protocol(said!("the server continued a cancelled password authentication")));
}
let answer = if sent {
cancelled = true;
"*"
} else {
sent = true;
response.as_str()
};
log::trace!("C: ***");
self.wire.write(format!("{answer}\r\n").as_bytes())?;
self.wire.flush()?;
};
match verdict.status {
_ if cancelled => Err(ProtoError::Auth(said!("the server requested more than one PLAIN response"))),
Status::Ok if !sent => Err(ProtoError::Protocol(said!("the server accepted a password that was not sent"))),
Status::Ok => {
self.authenticated = true;
Ok(())
}
Status::No => Err(ProtoError::Auth(self.refusal(&verdict))),
_ => Err(ProtoError::Rejected(self.refusal(&verdict))),
}
}
}
+112
View File
@@ -0,0 +1,112 @@
// SPDX-FileCopyrightText: MailCraft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
use crate::script::Script;
use base64::{Engine as _, engine::general_purpose::STANDARD};
fn greeting(caps: &str, replies: &str) -> String {
format!("* OK [CAPABILITY IMAP4rev1 {caps}] ready\r\n{replies}")
}
#[test]
fn plain_uses_an_initial_response_only_when_advertised() {
let payload = STANDARD.encode(b"\0user@example.org\0invented");
for inline in [false, true] {
let caps = if inline { "AUTH=PLAIN SASL-IR LOGINDISABLED" } else { "AUTH=PLAIN LOGINDISABLED" };
let replies = if inline { "A0001 OK welcome\r\n" } else { "+ continue\r\nA0001 OK welcome\r\n" };
let mut stream = Script::new(greeting(caps, replies));
let mut imap = Imap::connect(&mut stream).unwrap();
imap.authenticate_password("user@example.org", "invented").unwrap();
assert!(imap.is_authenticated());
let expected = if inline { format!("A0001 AUTHENTICATE PLAIN {payload}\r\n") } else { format!("A0001 AUTHENTICATE PLAIN\r\n{payload}\r\n") };
assert_eq!(stream.sent(), expected);
}
}
#[test]
fn login_remains_available_when_plain_is_not_advertised() {
let mut stream = Script::new(greeting("SASL-IR", "A0001 OK welcome\r\n"));
Imap::connect(&mut stream).unwrap().authenticate_password("user@example.org", "invented").unwrap();
assert_eq!(stream.sent(), "A0001 LOGIN \"user@example.org\" \"invented\"\r\n");
}
#[test]
fn a_plain_refusal_is_redacted_and_never_retried_with_login() {
let payload = STANDARD.encode(b"\0user@example.org\0invented");
let mut stream = Script::new(greeting("AUTH=PLAIN SASL-IR", &format!("A0001 NO [AUTHENTICATIONFAILED] invented {payload}\r\n")));
let mut imap = Imap::connect(&mut stream).unwrap();
let error = imap.authenticate_password("user@example.org", "invented").unwrap_err();
assert!(matches!(error, ProtoError::Auth(_)));
assert!(!format!("{error:?} {imap:?}").contains("invented"));
assert!(!format!("{error:?} {imap:?}").contains(&payload));
assert!(!imap.is_authenticated());
assert!(!stream.sent().contains(" LOGIN "));
}
#[test]
fn a_refusal_before_the_challenge_sends_no_password() {
let mut stream = Script::new(greeting("AUTH=PLAIN", "A0001 NO unavailable\r\n"));
assert!(Imap::connect(&mut stream).unwrap().authenticate_password("user@example.org", "invented").is_err());
assert_eq!(stream.sent(), "A0001 AUTHENTICATE PLAIN\r\n");
}
#[test]
fn repeated_challenges_cancel_and_never_authenticate() {
for replies in ["+ first\r\n+ second\r\nA0001 OK ignored\r\n", "+ first\r\n+ second\r\n+ third\r\n"] {
let mut stream = Script::new(greeting("AUTH=PLAIN", replies));
let mut imap = Imap::connect(&mut stream).unwrap();
assert!(imap.authenticate_password("user@example.org", "invented").is_err());
assert!(!imap.is_authenticated());
assert!(stream.sent().ends_with("\r\n*\r\n"));
}
}
#[test]
fn premature_success_and_invalid_credentials_are_refused() {
let mut stream = Script::new(greeting("AUTH=PLAIN", "A0001 OK too early\r\n"));
assert!(Imap::connect(&mut stream).unwrap().authenticate_password("user@example.org", "invented").is_err());
for (user, password) in [("", "invented"), ("user@example.org", ""), ("bad\0user", "invented"), ("user@example.org", "bad\0password")] {
let mut stream = Script::new(greeting("AUTH=PLAIN", ""));
assert!(Imap::connect(&mut stream).unwrap().authenticate_password(user, password).is_err());
assert!(stream.sent().is_empty());
}
let mut stream = Script::new(greeting("AUTH=PLAIN", ""));
assert!(Imap::connect(&mut stream).unwrap().authenticate_password("user@example.org", &"x".repeat(32769)).is_err());
assert!(stream.sent().is_empty());
}
#[test]
fn utf8_and_line_breaks_are_encoded_not_protocol_lines() {
let mut stream = Script::new(greeting("auth=plain sasl-ir", "A0001 OK welcome\r\n"));
Imap::connect(&mut stream).unwrap().authenticate_password("user@example.org", "päss\r\nword").unwrap();
assert_eq!(stream.sent().lines().count(), 1);
assert!(stream.sent().contains(&STANDARD.encode("\0user@example.org\0päss\r\nword".as_bytes())));
}
#[test]
fn unknown_capabilities_are_queried_once_by_password_authentication() {
let mut stream = Script::new("* OK ready\r\n* CAPABILITY IMAP4rev1 AUTH=PLAIN SASL-IR\r\nA0001 OK done\r\nA0002 OK welcome\r\n");
Imap::connect(&mut stream).unwrap().authenticate_password("user@example.org", "invented").unwrap();
assert!(stream.sent().starts_with("A0001 CAPABILITY\r\nA0002 AUTHENTICATE PLAIN "));
assert_eq!(stream.sent().matches(" CAPABILITY").count(), 1);
}
#[test]
fn a_missing_password_has_its_own_message_without_network_commands() {
let mut stream = Script::new("* OK ready\r\n");
let error = Imap::connect(&mut stream).unwrap().authenticate_password("user@example.org", "").unwrap_err();
assert!(error.to_string().contains("enter a password"));
assert!(!error.to_string().contains("NUL"));
assert!(stream.sent().is_empty());
}
#[test]
fn an_empty_user_name_is_explained_before_any_commands() {
for text in ["* OK ready\r\n".to_string(), greeting("AUTH=PLAIN", ""), greeting("", "")] {
let mut stream = Script::new(text);
let error = Imap::connect(&mut stream).unwrap().authenticate_password("", "invented").unwrap_err();
assert!(error.to_string().contains("enter a user name"));
assert!(!error.to_string().contains("NUL"));
assert!(stream.sent().is_empty());
}
}
+164
View File
@@ -0,0 +1,164 @@
// SPDX-FileCopyrightText: MailCraft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
//! STATUS (RFC 3501 §6.3.10): what a mailbox holds, asked without opening it, for a program to
//! tell whether it has changed since it was last read (#276). Many mailboxes are asked in one
//! go: the commands are written together and the answers read together (pipelining, RFC 3501
//! §5.5), so a hundred mailboxes cost about one round trip, not a hundred.
use std::io::{Read, Write};
use super::parse::{Status, Value};
use super::{Command, Imap, MAX_COMMAND_TEXT, MAX_QUOTED, Part, Response};
use crate::i18n::said;
use crate::{ProtoError, for_trace};
/// Most mailboxes asked in one go: their commands are a few kilobytes at most, so the server
/// can't be left waiting to be read while we write.
pub const MAX_STATUS_BATCH: usize = 50;
/// What STATUS says of a mailbox: all four counts, or nothing at all (a server that leaves one
/// out gets its mailbox read, never passed over on a guess).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct FolderStatus {
/// How many messages there are.
pub messages: u32,
/// The UID the next message to arrive gets.
pub uid_next: u32,
pub uid_validity: u32,
/// How many are not marked `\Seen`.
pub unseen: u32,
}
/// From `STATUS name (MESSAGES 3 UIDNEXT 9 …)`; `None` when it isn't one, or a count is missing.
fn status_from(values: Vec<Value>) -> Option<FolderStatus> {
let mut values = values.into_iter();
if !values.next()?.atom()?.eq_ignore_ascii_case("STATUS") {
return None;
}
values.next()?;
let Value::List(pairs) = values.next()? else { return None };
let (mut messages, mut uid_next, mut uid_validity, mut unseen) = (None, None, None, None);
let mut pairs = pairs.into_iter();
while let (Some(name), Some(value)) = (pairs.next(), pairs.next()) {
let Some(number) = value.number() else { continue };
match name.atom().map(str::to_ascii_uppercase).as_deref() {
Some("MESSAGES") => messages = Some(number),
Some("UIDNEXT") => uid_next = Some(number),
Some("UIDVALIDITY") => uid_validity = Some(number),
Some("UNSEEN") => unseen = Some(number),
_ => {}
}
}
Some(FolderStatus { messages: messages?, uid_next: uid_next?, uid_validity: uid_validity?, unseen: unseen? })
}
fn command(raw_name: &str) -> Command<'_> {
Command::new("STATUS").string(raw_name.as_bytes()).arg("(MESSAGES UIDNEXT UIDVALIDITY UNSEEN)")
}
impl<S: Read + Write> Imap<S> {
/// STATUS of one mailbox; `None` when the server refuses or leaves a count out.
pub fn status(&mut self, raw_name: &str) -> Result<Option<FolderStatus>, ProtoError> {
let mut found = None;
let line = self.exchange(command(raw_name), &mut |values| {
if found.is_none() {
found = status_from(values);
}
})?;
Ok(found.filter(|_| line.status == Status::Ok))
}
/// STATUS of each of `raw_names`, in the same order, `None` for one the server refuses or
/// leaves a count out of. At most [`MAX_STATUS_BATCH`] are asked in one go; a name that
/// can't go in a quoted string is asked alone.
///
/// An error is the connection's: the answers read before it are lost with it.
pub fn status_many(&mut self, raw_names: &[&str]) -> Result<Vec<Option<FolderStatus>>, ProtoError> {
let mut out = Vec::with_capacity(raw_names.len());
for batch in raw_names.chunks(MAX_STATUS_BATCH) {
let plain = batch.iter().all(|name| name.len() <= MAX_QUOTED && name.bytes().all(|b| matches!(b, b' '..=b'~')));
if plain && batch.len() > 1 {
out.extend(self.status_batch(batch)?);
} else {
for name in batch {
out.push(self.status(name)?);
}
}
}
Ok(out)
}
/// One batch, written together: the answers come in the order of the commands.
fn status_batch(&mut self, batch: &[&str]) -> Result<Vec<Option<FolderStatus>>, ProtoError> {
let mut tags = Vec::with_capacity(batch.len());
let mut out = Vec::with_capacity(batch.len().saturating_mul(64));
for name in batch {
let command = command(name);
if command.unsendable {
return Err(ProtoError::Protocol(said!("the text has a character that can't be sent")));
}
let tag = self.tag();
if log::log_enabled!(log::Level::Trace) {
log::trace!("C: {tag} {}", for_trace(&self.secrets.hide(&command.for_log())));
}
out.extend_from_slice(tag.as_bytes());
out.push(b' ');
for part in &command.parts {
if let Part::Text(text) = part {
out.extend_from_slice(text);
}
}
out.extend_from_slice(b"\r\n");
tags.push(tag);
}
self.wire.write(&out)?;
self.wire.flush()?;
self.text_seen = 0;
let mut found: Vec<Option<FolderStatus>> = vec![None; batch.len()];
let mut answered = 0usize;
// Each command brings one STATUS and its tagged answer; the rest is slack for what a
// server says unasked.
let cap = batch.len().saturating_mul(2).saturating_add(64);
for _ in 0..cap {
if answered >= tags.len() {
break;
}
match self.read_response()? {
Response::GoAhead => return Err(ProtoError::Protocol(said!("the server asked for more than the command had"))),
Response::Status { tag: Some(tag), line } => {
if tags.get(answered) != Some(&tag) || !matches!(line.status, Status::Ok | Status::No | Status::Bad) {
return Err(ProtoError::Protocol(said!("the server answered a command that wasn't sent")));
}
self.note_status(&line);
if line.status != Status::Ok
&& let Some(slot) = found.get_mut(answered)
{
*slot = None;
}
answered += 1;
}
Response::Status { tag: None, line } => {
if line.status == Status::Bye && !self.leaving {
return Err(ProtoError::Io(said!("the server ended the session")));
}
self.note_status(&line);
}
Response::Data(values) => {
if self.text_seen > MAX_COMMAND_TEXT {
return Err(ProtoError::Protocol(said!("the server sent too much in answer to one command")));
}
self.note_data(&values);
if let Some(slot) = found.get_mut(answered)
&& slot.is_none()
{
*slot = status_from(values);
}
}
}
}
if answered < tags.len() {
return Err(ProtoError::Protocol(said!("the server sent too many responses to one command")));
}
Ok(found)
}
}
+78
View File
@@ -0,0 +1,78 @@
// SPDX-FileCopyrightText: MailCraft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use proptest::prelude::*;
use super::*;
use crate::script::Script;
fn status(messages: u32, uid_next: u32, uid_validity: u32, unseen: u32) -> FolderStatus {
FolderStatus { messages, uid_next, uid_validity, unseen }
}
#[test]
fn one_mailbox_is_asked_its_four_counts() {
let mut s = Script::new("* STATUS \"Work\" (MESSAGES 3 UIDNEXT 9 UIDVALIDITY 77 UNSEEN 1)\r\nA0001 OK done\r\n");
let got = Imap::resume(&mut s).status("Work").unwrap();
assert_eq!(got, Some(status(3, 9, 77, 1)));
assert_eq!(s.sent(), "A0001 STATUS \"Work\" (MESSAGES UIDNEXT UIDVALIDITY UNSEEN)\r\n");
}
#[test]
fn a_count_left_out_or_a_refusal_is_no_status() {
let mut s = Script::new("* STATUS Work (MESSAGES 3 UIDNEXT 9 UIDVALIDITY 77)\r\nA0001 OK done\r\nA0002 NO [NONEXISTENT] no such mailbox\r\n");
let mut imap = Imap::resume(&mut s);
assert_eq!(imap.status("Work").unwrap(), None);
assert_eq!(imap.status("Gone").unwrap(), None);
}
#[test]
fn many_mailboxes_are_asked_in_one_write() {
let mut s = Script::new(
"* STATUS A (MESSAGES 1 UIDNEXT 2 UIDVALIDITY 5 UNSEEN 0)\r\nA0001 OK done\r\n\
A0002 NO [NONEXISTENT] no\r\n\
* STATUS \"C d\" (UNSEEN 4 UIDVALIDITY 7 UIDNEXT 8 MESSAGES 9 HIGHESTMODSEQ 12)\r\nA0003 OK done\r\n",
);
let got = Imap::resume(&mut s).status_many(&["A", "B", "C d"]).unwrap();
assert_eq!(got, vec![Some(status(1, 2, 5, 0)), None, Some(status(9, 8, 7, 4))]);
let sent = s.sent();
assert_eq!(sent.matches("STATUS").count(), 3);
assert!(sent.starts_with("A0001 STATUS \"A\" ") && sent.contains("A0003 STATUS \"C d\" "), "{sent}");
}
#[test]
fn answers_out_of_turn_or_too_many_end_the_session_not_the_program() {
let mut s = Script::new("A0002 OK done\r\n");
assert!(matches!(Imap::resume(&mut s).status_many(&["A", "B"]), Err(ProtoError::Protocol(_))));
let flood = "* 1 EXISTS\r\n".repeat(500);
let mut s = Script::new(flood);
assert!(matches!(Imap::resume(&mut s).status_many(&["A", "B"]), Err(ProtoError::Protocol(_))));
let mut s = Script::new("* BYE going\r\n");
assert!(matches!(Imap::resume(&mut s).status_many(&["A", "B"]), Err(ProtoError::Io(_))));
}
#[test]
fn a_name_that_needs_a_literal_is_asked_alone() {
let mut s = Script::new("+ go\r\n* STATUS x (MESSAGES 1 UIDNEXT 2 UIDVALIDITY 3 UNSEEN 0)\r\nA0001 OK done\r\n");
let got = Imap::resume(&mut s).status_many(&["é", "A"]).unwrap_or_default();
assert!(got.len() <= 2);
}
proptest! {
#[test]
fn arbitrary_server_bytes_never_panic_in_status(server in proptest::collection::vec(any::<u8>(), 0..600), names in 0usize..120) {
let list: Vec<String> = (0..names).map(|n| format!("F{n}")).collect();
let refs: Vec<&str> = list.iter().map(String::as_str).collect();
let mut s = Script::new(&server);
let got = Imap::resume(&mut s).status_many(&refs);
if let Ok(got) = got {
prop_assert_eq!(got.len(), names);
}
}
#[test]
fn any_status_line_is_read_or_not(line in "[ -~]{0,80}") {
let mut s = Script::new(format!("* STATUS {line}\r\nA0001 OK done\r\n"));
let _ = Imap::resume(&mut s).status("x");
}
}
File diff suppressed because it is too large. Load diff
+175
View File
@@ -0,0 +1,175 @@
// SPDX-FileCopyrightText: MailCraft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
//! Modified UTF-7, the encoding of mailbox names (RFC 3501 §5.1.3).
//!
//! Printable ASCII stands for itself, except `&`, which is written `&-`. Everything else is
//! UTF-16 in base64 (with `,` in place of `/`, and no padding) between `&` and `-`.
const DIGITS: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,";
fn digit(six_bits: u32) -> char {
DIGITS.get((six_bits & 0x3F) as usize).map_or('A', |b| char::from(*b))
}
/// A mailbox name as people read it. Text that isn't valid modified UTF-7 is kept as it is.
pub fn decode_utf7(name: &str) -> String {
let mut out = String::with_capacity(name.len());
let mut rest = name;
// Every round takes at least the `&` off `rest`.
while let Some(at) = rest.find('&') {
out.push_str(rest.get(..at).unwrap_or(""));
let after = rest.get(at + 1..).unwrap_or("");
rest = match after.find('-') {
Some(0) => {
out.push('&');
after.get(1..).unwrap_or("")
}
Some(end) => match shifted(after.get(..end).unwrap_or("")) {
Some(text) => {
out.push_str(&text);
after.get(end + 1..).unwrap_or("")
}
// Not base64 after all: an ampersand like any other character.
None => {
out.push('&');
after
}
},
None => {
out.push('&');
after
}
};
}
out.push_str(rest);
out
}
/// The text of one base64 run, or `None` when it isn't one.
fn shifted(encoded: &str) -> Option<String> {
let mut units = Vec::with_capacity(encoded.len() * 3 / 8 + 1);
let (mut bits, mut count) = (0u32, 0u32);
for b in encoded.bytes() {
let value = DIGITS.iter().position(|d| *d == b)? as u32;
bits = (bits << 6) | value;
count += 6;
if count >= 16 {
count -= 16;
units.push((bits >> count) as u16);
bits &= (1 << count) - 1;
}
}
// What is left over is padding: less than one digit's worth.
if count >= 6 || units.is_empty() {
return None;
}
String::from_utf16(&units).ok()
}
/// A mailbox name as a server wants it.
pub fn encode_utf7(name: &str) -> String {
let mut out = String::with_capacity(name.len());
let mut pending: Vec<u16> = Vec::new();
for c in name.chars() {
if matches!(c, ' '..='~') {
flush(&mut pending, &mut out);
out.push(c);
if c == '&' {
out.push('-');
}
} else {
let mut units = [0u16; 2];
pending.extend_from_slice(c.encode_utf16(&mut units));
}
}
flush(&mut pending, &mut out);
out
}
/// Write the characters waiting to be encoded as one base64 run.
fn flush(pending: &mut Vec<u16>, out: &mut String) {
if pending.is_empty() {
return;
}
out.push('&');
let (mut bits, mut count) = (0u32, 0u32);
for unit in pending.drain(..) {
bits = (bits << 16) | u32::from(unit);
count += 16;
while count >= 6 {
count -= 6;
out.push(digit(bits >> count));
}
bits &= (1 << count) - 1;
}
if count > 0 {
out.push(digit(bits << (6 - count)));
}
out.push('-');
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use proptest::prelude::*;
use super::*;
#[test]
fn the_examples_of_the_rfc() {
// RFC 3501 §5.1.3.
assert_eq!(decode_utf7("~peter/mail/&U,BTFw-/&ZeVnLIqe-"), "~peter/mail/台北/日本語");
assert_eq!(encode_utf7("~peter/mail/台北/日本語"), "~peter/mail/&U,BTFw-/&ZeVnLIqe-");
assert_eq!(decode_utf7("&Jjo-!"), "☺!");
assert_eq!(encode_utf7("☺!"), "&Jjo-!");
}
#[test]
fn ordinary_names() {
assert_eq!(encode_utf7("INBOX"), "INBOX");
assert_eq!(encode_utf7("Tom & Jerry"), "Tom &- Jerry");
assert_eq!(decode_utf7("Tom &- Jerry"), "Tom & Jerry");
assert_eq!(encode_utf7("Entwürfe"), "Entw&APw-rfe");
assert_eq!(decode_utf7("Entw&APw-rfe"), "Entwürfe");
assert_eq!(encode_utf7("Gelöschte Elemente"), "Gel&APY-schte Elemente");
// Outside the basic plane: a surrogate pair.
assert_eq!(decode_utf7(&encode_utf7("📬 Post")), "📬 Post");
assert_eq!(encode_utf7("📬"), "&2D3c7A-");
// Control characters are encoded too.
assert_eq!(encode_utf7("a\tb"), "a&AAk-b");
assert_eq!(encode_utf7(""), "");
}
#[test]
fn junk_is_kept_as_it_is() {
for junk in ["&", "a&b", "&&&", "&!!!-", "&A-", "&AAAAA-x", "R&D", "&2D0-", "&-&", "é&é-"] {
let decoded = decode_utf7(junk);
assert!(!decoded.is_empty(), "{junk}");
}
assert_eq!(decode_utf7("R&D"), "R&D");
assert_eq!(decode_utf7("&!!!-"), "&!!!-");
// A lone surrogate is not text.
assert_eq!(decode_utf7("&2D0-"), "&2D0-");
assert_eq!(decode_utf7("AT&T-Mobile"), "AT&T-Mobile");
}
proptest! {
#[test]
fn any_name_round_trips(name in "\\PC{0,40}") {
let encoded = encode_utf7(&name);
prop_assert!(encoded.bytes().all(|b| (0x20..=0x7E).contains(&b)), "{encoded}");
prop_assert_eq!(decode_utf7(&encoded), name);
}
#[test]
fn any_text_round_trips_with_control_characters(name in proptest::collection::vec(any::<char>(), 0..40)) {
let name: String = name.into_iter().collect();
prop_assert_eq!(decode_utf7(&encode_utf7(&name)), name);
}
#[test]
fn decoding_never_panics(name in "[&A-Za-z0-9+,\\-é ]{0,60}") {
let _ = decode_utf7(&name);
}
}
}
+229
View File
@@ -0,0 +1,229 @@
// SPDX-FileCopyrightText: Craft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
//! Mail protocols without sockets.
//!
//! [`smtp::Smtp`] and [`imap::Imap`] speak SMTP (RFC 5321, 3207, 4954) and IMAP4rev1 (RFC 3501,
//! 4315, 4959, 6154, 6851) over any `Read + Write` stream: a TLS socket on the desktop, a scripted
//! transcript in the tests. Everything a server sends is treated as hostile: lines, literals and
//! response counts are capped, and nothing here panics on junk.
//!
//! Passwords and access tokens never reach a log or an error text, even when a server echoes
//! them back.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
pub mod i18n;
pub mod imap;
mod line;
pub mod smtp;
#[cfg(test)]
mod script;
use base64::{Engine as _, engine::general_purpose::STANDARD};
use i18n::{Arg, Text};
pub(crate) use i18n::{for_trace, tidy};
/// Longest line a server may send.
pub const MAX_LINE: usize = 64 * 1024;
/// Largest counted block (an IMAP literal, so: the largest message) a server may send.
pub const MAX_LITERAL: usize = 64 * 1024 * 1024;
/// Longest user name and access token, together, that one sign-in may carry.
const MAX_XOAUTH2: usize = 32 * 1024;
/// What went wrong. Each holds the reason as a [`Text`]: Craft's own words are a template
/// displayed in its language ([`said!`]), and what a server or the system said is kept as
/// it said it ([`Text::verbatim`]). The English ([`Display`](std::fmt::Display)) is what the CLI, MCP
/// and the log read, and it is the same either way.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ProtoError {
Io(Text),
Protocol(Text),
/// The server refused the command (IMAP NO/BAD, SMTP 4xx/5xx); the text is the server's.
Rejected(Text),
Auth(Text),
}
impl ProtoError {
/// The underlying reason, without its error category prefix.
pub fn reason(&self) -> &Text {
match self {
Self::Io(why) | Self::Protocol(why) | Self::Rejected(why) | Self::Auth(why) => why,
}
}
/// The error as the user is told it: what kind of trouble, and why.
pub fn said(&self) -> Text {
match self {
ProtoError::Io(why) => said!("connection problem: {reason}", reason = Arg::said(why.clone())),
ProtoError::Protocol(why) => said!("unexpected server response: {reason}", reason = Arg::said(why.clone())),
ProtoError::Rejected(why) => said!("the server said: {reason}", reason = Arg::said(why.clone())),
ProtoError::Auth(why) => said!("sign-in failed: {reason}", reason = Arg::said(why.clone())),
}
}
}
impl std::fmt::Display for ProtoError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
std::fmt::Display::fmt(&self.said(), f)
}
}
impl std::error::Error for ProtoError {}
/// Secrets: passwords and tokens, never shown in logs or errors.
#[derive(Default)]
pub(crate) struct Secrets(Vec<zeroize::Zeroizing<String>>);
impl Secrets {
pub(crate) fn add(&mut self, secret: &str) {
if !secret.is_empty() && !self.0.iter().any(|s| s.as_str() == secret) {
self.0.push(zeroize::Zeroizing::new(secret.to_owned()));
// Longer overlapping secrets must be hidden before their prefixes.
self.0.sort_by_key(|s| std::cmp::Reverse(s.len()));
}
}
pub(crate) fn hide(&self, text: &str) -> String {
self.0.iter().fold(text.to_owned(), |text, secret| text.replace(secret.as_str(), "***"))
}
}
/// Build a bounded, base64-encoded SASL XOAUTH2 initial response.
pub(crate) fn xoauth2(user: &str, token: &str) -> Result<String, ProtoError> {
if user.is_empty() || token.is_empty() || user.chars().chain(token.chars()).any(char::is_control) {
return Err(ProtoError::Auth(said!("the user name or token has a character that can't be sent")));
}
if user.len().saturating_add(token.len()) > MAX_XOAUTH2 {
return Err(ProtoError::Auth(said!("the user name or token is too long")));
}
let plain = zeroize::Zeroizing::new(format!("user={user}\x01auth=Bearer {token}\x01\x01"));
Ok(STANDARD.encode(plain.as_bytes()))
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
#[test]
fn secrets_redact_overlapping_values() {
let mut secrets = Secrets::default();
secrets.add("token");
secrets.add("token-long");
assert_eq!(secrets.hide("token-long token"), "*** ***");
}
#[test]
fn xoauth2_rejects_injection_and_oversized_values() {
assert!(xoauth2("user\x01auth=Bearer injected", "token").is_err());
assert!(xoauth2("user", &"x".repeat(MAX_XOAUTH2)).is_err());
}
#[test]
fn error_display() {
let err = ProtoError::Io(said!("connection problem"));
assert_eq!(err.to_string(), "connection problem: connection problem");
assert_eq!(err.reason().to_string(), "connection problem");
}
#[test]
fn error_said() {
let err = ProtoError::Auth(said!("invalid password"));
assert_eq!(err.said().to_string(), "sign-in failed: invalid password");
}
#[test]
fn xoauth2_format() {
let result = xoauth2("user@example.com", "token123").unwrap();
let result = String::from_utf8(STANDARD.decode(result).unwrap()).unwrap();
assert!(result.contains("user=user@example.com"));
assert!(result.contains("auth=Bearer token123"));
}
}
#[cfg(test)]
mod source_regression_tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
#[test]
fn the_wire_trace_keeps_keywords_and_no_address_name_or_text() {
// (Line, what the trace shows.)
for (line, _old_shown) in [
("A0001 OK ada@example.org authenticated (Success)\r\n", "A0001 OK … (39 bytes)"),
("A0002 LOGIN ***", "A0002 LOGIN ***"),
("MAIL FROM:<ada@example.org> SIZE=120", "MAIL FROM: … (26 bytes)"),
("RCPT TO:<bob@example.org>", "RCPT TO: … (17 bytes)"),
("550 5.1.1 <bob@example.org>: Recipient address rejected", "550 5.1.1 … (45 bytes)"),
("250-mx.example.org at your service", "250- … (30 bytes)"),
("250-AUTH LOGIN PLAIN XOAUTH2", "250-AUTH LOGIN PLAIN XOAUTH2"),
("A0003 SELECT \"Letters from Grace\"", "A0003 SELECT … (20 bytes)"),
("* LIST (\\HasNoChildren) \"/\" Grace", "* LIST … (26 bytes)"),
("* 12 FETCH (UID 40 FLAGS (\\Seen) BODY[HEADER.FIELDS (SUBJECT)] \"Subject: Quarterly figures\")", "* 12 FETCH … (81 bytes)"),
("* 3 EXISTS", "* 3 EXISTS"),
("UID FETCH 1:40,42 (UID FLAGS)", "UID FETCH 1:40,42 … (11 bytes)"),
("hello there", "(11 bytes)"),
("", ""),
] {
let traced = for_trace(line);
assert!(traced.len() <= line.len().saturating_add(32), "{line:?}");
for private in ["ada", "bob", "Grace", "Quarterly", "mx.example"] {
assert!(!traced.contains(private), "{line:?}: {traced}");
}
}
assert!(for_trace(&format!("A0001 OK {}", "X ".repeat(500))).len() < 160);
assert_eq!(for_trace("ünïcödé ä"), "(14 bytes)");
}
#[test]
fn uppercase_private_text_is_not_protocol_structure() {
assert_eq!(for_trace("550 CUSTOMER ALICE PAYMENT OVERDUE"), "550 … (30 bytes)");
assert_eq!(for_trace("A0003 SELECT PRIVATE_MAILBOX"), "A0003 SELECT … (15 bytes)");
assert_eq!(for_trace("250-PRIVATE_CUSTOMER_DOMAIN"), "250- … (23 bytes)");
assert_eq!(for_trace("A0001 OK PRIVATE CUSTOMER"), "A0001 OK … (16 bytes)");
}
#[test]
fn secrets_are_hidden_longest_first() {
let mut s = Secrets::default();
s.add("hunter2");
s.add("hunter2-and-more");
s.add("");
assert_eq!(s.hide("no hunter2-and-more, no hunter2, nothing"), "no ***, no ***, nothing");
assert_eq!(Secrets::default().hide("plain"), "plain");
}
#[test]
fn the_xoauth2_response_is_user_and_bearer_token_between_control_a() {
let decoded = |payload: String| STANDARD.decode(payload).unwrap();
assert_eq!(decoded(xoauth2("ada@example.org", "tok.en-123").unwrap()), b"user=ada@example.org\x01auth=Bearer tok.en-123\x01\x01");
// The example of the mechanism's description.
assert_eq!(
xoauth2("someuser@example.com", "ya29.vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg").unwrap(),
"dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ=="
);
assert_eq!(decoded(xoauth2("ädä", "t").unwrap()), "user=ädä\x01auth=Bearer t\x01\x01".as_bytes());
// Nothing that could end the name, the token or the line early.
for (user, token) in [("ada\x01auth=Bearer other", "t"), ("ada", "t\x01"), ("ada\r\n", "t"), ("ada", "t\nQUIT"), ("a\0", "t"), ("ada", "\0")]
{
assert!(matches!(xoauth2(user, token), Err(ProtoError::Auth(_))), "{user:?} {token:?}");
}
assert!(matches!(xoauth2("ada", ""), Err(ProtoError::Auth(_))));
assert!(xoauth2("ada", &"t".repeat(MAX_XOAUTH2 - 3)).is_ok());
let err = xoauth2("ada", &"t".repeat(MAX_XOAUTH2)).unwrap_err();
assert!(matches!(&err, ProtoError::Auth(why) if why.to_string().len() < 100), "{err:?}");
}
#[test]
fn server_text_is_tidied() {
assert_eq!(tidy(" 5.7.8\tBad\r\n credentials \u{7}"), "5.7.8 Bad credentials");
let long = tidy(&"é".repeat(1000));
assert_eq!(long.chars().count(), 301);
assert!(long.ends_with('…'));
assert_eq!(tidy(""), "");
}
}
+318
View File
@@ -0,0 +1,318 @@
// SPDX-FileCopyrightText: MailCraft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
//! The bounded reader both protocols share: lines and counted blocks from a stream that may be hostile.
use std::io::{ErrorKind, Read, Write};
use crate::said;
use crate::{MAX_LINE, MAX_LITERAL, ProtoError};
/// How much is asked of the stream in one read.
const CHUNK: usize = 16 * 1024;
/// Most bytes of one over-long untagged line read past ([`Wire::read_line_or_skip`]).
const MAX_SKIPPED: usize = 4 * 1024 * 1024;
/// Reads interrupted in a row before giving up.
const MAX_INTERRUPTS: u32 = 1_000;
/// A stream with the bytes read ahead of what was asked for.
pub(crate) struct Wire<S> {
stream: S,
/// Bytes read from the stream and not handed out yet (from `start`).
buf: Vec<u8>,
start: usize,
// Bytes already searched for a newline in the current pending polling line.
poll_scanned: usize,
}
fn closed() -> ProtoError {
ProtoError::Io(said!("the server closed the connection"))
}
fn io_error(e: &std::io::Error) -> ProtoError {
match e.kind() {
ErrorKind::TimedOut | ErrorKind::WouldBlock => ProtoError::Io(said!("the server took too long to answer")),
ErrorKind::UnexpectedEof | ErrorKind::ConnectionAborted | ErrorKind::ConnectionReset | ErrorKind::BrokenPipe => closed(),
// The system's own words, as it said them.
_ => ProtoError::Io(crate::tidy(&e.to_string()).into()),
}
}
impl<S> Wire<S> {
pub(crate) fn new(stream: S) -> Self {
Wire { stream, buf: Vec::new(), start: 0, poll_scanned: 0 }
}
/// Whether the server sent more than has been read so far.
pub(crate) fn has_pending(&self) -> bool {
self.start < self.buf.len()
}
pub(crate) fn into_inner(self) -> S {
self.stream
}
/// The stream itself, for its owner to set up (what a socket waits for, say). Reading from
/// it or writing to it here would take the session apart.
pub(crate) fn get_mut(&mut self) -> &mut S {
&mut self.stream
}
}
impl<S: Read + Write> Wire<S> {
/// Read some more into the buffer; the end of the stream is an error.
fn fill(&mut self) -> Result<(), ProtoError> {
self.poll_scanned = 0;
if self.start > 0 {
self.buf.drain(..self.start.min(self.buf.len()));
self.start = 0;
}
let mut tmp = vec![0u8; CHUNK];
let n = read_some(&mut self.stream, &mut tmp)?;
self.buf.extend_from_slice(tmp.get(..n).unwrap_or(&[]));
Ok(())
}
/// The next line without its line ending (CRLF, or a bare LF).
pub(crate) fn read_line(&mut self) -> Result<Vec<u8>, ProtoError> {
self.next_line(false)?.ok_or_else(too_long)
}
/// The next line, or `None` for an untagged one (`* …`) longer than [`MAX_LINE`], which is
/// read past to its end (at most [`MAX_SKIPPED`] bytes of it) so that the session goes on.
/// Any other line that long is an error, as for [`Wire::read_line`].
pub(crate) fn read_line_or_skip(&mut self) -> Result<Option<Vec<u8>>, ProtoError> {
self.next_line(true)
}
fn next_line(&mut self, skip: bool) -> Result<Option<Vec<u8>>, ProtoError> {
self.poll_scanned = 0;
// How much of the pending bytes has been searched for a line feed already.
let mut scanned = 0usize;
// Bytes of an over-long line dropped so far, when one is being read past.
let mut skipped: Option<usize> = None;
loop {
let pending = self.buf.get(self.start..).unwrap_or(&[]);
if let Some(i) = pending.get(scanned..).and_then(|rest| rest.iter().position(|b| *b == b'\n')) {
let end = scanned.saturating_add(i);
let line = pending.get(..end).unwrap_or(&[]);
let line = line.strip_suffix(b"\r").unwrap_or(line);
let line = if skipped.is_some() {
None
} else if line.len() > MAX_LINE {
if !(skip && line.starts_with(b"* ")) {
return Err(too_long());
}
None
} else {
Some(line.to_vec())
};
self.start = self.start.saturating_add(end).saturating_add(1);
return Ok(line);
}
scanned = pending.len();
// The limit is on the line itself; a CR may still come on top.
if scanned > MAX_LINE + 1 {
let dropped = match skipped {
Some(n) => n,
None if skip && pending.starts_with(b"* ") => 0,
None => return Err(too_long()),
};
let dropped = dropped.saturating_add(scanned);
if dropped > MAX_SKIPPED {
return Err(too_long());
}
skipped = Some(dropped);
self.start = self.buf.len();
scanned = 0;
}
// Each round reads at least one byte, so this ends at the line feed, the cap or the end of the stream.
self.fill()?;
}
}
/// The next line after at most one underlying read; `None` for a partial line or when
/// the stream times out (IDLE waits like this, a second at a time, so that its owner can
/// look at the clock and at whether it was told to stop). Bytes of a line that came so far are
/// kept for the next call. A line over [`MAX_LINE`] is an error, as for [`Wire::read_line`].
pub(crate) fn poll_line(&mut self) -> Result<Option<Vec<u8>>, ProtoError> {
let mut read_once = false;
loop {
let pending = self.buf.get(self.start..).unwrap_or(&[]);
let scanned = self.poll_scanned.min(pending.len());
if let Some(offset) = pending.get(scanned..).unwrap_or(&[]).iter().position(|b| *b == b'\n') {
let end = scanned.saturating_add(offset);
let line = pending.get(..end).unwrap_or(&[]);
let line = line.strip_suffix(b"\r").unwrap_or(line);
if line.len() > MAX_LINE {
return Err(too_long());
}
let line = line.to_vec();
self.start = self.start.saturating_add(end).saturating_add(1);
self.poll_scanned = 0;
return Ok(Some(line));
}
if pending.len() > MAX_LINE + 1 {
return Err(too_long());
}
self.poll_scanned = pending.len();
// One underlying read per poll lets the caller check cancellation even when
// a hostile peer trickles bytes without ever triggering the read timeout.
if read_once {
return Ok(None);
}
if self.start > 0 {
self.buf.drain(..self.start.min(self.buf.len()));
self.start = 0;
}
let mut tmp = vec![0u8; CHUNK];
read_once = true;
match self.stream.read(&mut tmp) {
Ok(0) => return Err(closed()),
Ok(n) => self.buf.extend_from_slice(tmp.get(..n.min(tmp.len())).unwrap_or(&[])),
Err(e) if matches!(e.kind(), ErrorKind::TimedOut | ErrorKind::WouldBlock | ErrorKind::Interrupted) => return Ok(None),
Err(e) => return Err(io_error(&e)),
}
}
}
/// Exactly `n` bytes (at most [`MAX_LITERAL`]).
pub(crate) fn read_block(&mut self, n: usize) -> Result<Vec<u8>, ProtoError> {
self.poll_scanned = 0;
if n > MAX_LITERAL {
return Err(ProtoError::Protocol(said!("the server sent {n} bytes in one piece, more than MailCraft accepts", n)));
}
// The size is the server's word: memory is taken as the bytes arrive.
let mut out = Vec::with_capacity(n.min(CHUNK));
let pending = self.buf.get(self.start..).unwrap_or(&[]);
let take = pending.len().min(n);
out.extend_from_slice(pending.get(..take).unwrap_or(&[]));
self.start = self.start.saturating_add(take);
let mut tmp = vec![0u8; CHUNK];
while out.len() < n {
let want = (n - out.len()).min(tmp.len());
let got = read_some(&mut self.stream, tmp.get_mut(..want).unwrap_or(&mut []))?;
out.extend_from_slice(tmp.get(..got.min(want)).unwrap_or(&[]));
}
Ok(out)
}
pub(crate) fn write(&mut self, mut bytes: &[u8]) -> Result<(), ProtoError> {
// Not `write_all`: that retries an interrupted write for ever.
let mut interrupts = 0;
while !bytes.is_empty() {
match self.stream.write(bytes) {
Ok(0) => return Err(closed()),
Ok(n) => bytes = bytes.get(n..).unwrap_or(&[]),
Err(e) if e.kind() == ErrorKind::Interrupted && interrupts < MAX_INTERRUPTS => interrupts += 1,
Err(e) => return Err(io_error(&e)),
}
}
Ok(())
}
pub(crate) fn flush(&mut self) -> Result<(), ProtoError> {
self.stream.flush().map_err(|e| io_error(&e))
}
}
fn too_long() -> ProtoError {
ProtoError::Protocol(said!("the server sent a line longer than {kb} KB", kb = MAX_LINE / 1024))
}
/// One read of at least one byte; the end of the stream is an error.
fn read_some<S: Read>(stream: &mut S, buf: &mut [u8]) -> Result<usize, ProtoError> {
let mut interrupts = 0;
loop {
match stream.read(buf) {
Ok(0) => return Err(closed()),
// A stream that claims more than the buffer holds is lying.
Ok(n) => return Ok(n.min(buf.len())),
Err(e) if e.kind() == ErrorKind::Interrupted && interrupts < MAX_INTERRUPTS => interrupts += 1,
Err(e) => return Err(io_error(&e)),
}
}
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
use crate::script::{Broken, Script};
#[test]
fn polling_reads_once_and_retains_linear_scan_progress() {
struct ByteAtATime {
bytes: std::io::Cursor<Vec<u8>>,
reads: usize,
}
impl Read for ByteAtATime {
fn read(&mut self, out: &mut [u8]) -> std::io::Result<usize> {
self.reads += 1;
self.bytes.read(&mut out[..1])
}
}
impl Write for ByteAtATime {
fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
Ok(bytes.len())
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
let mut wire = Wire::new(ByteAtATime { bytes: std::io::Cursor::new(b"abc\n".to_vec()), reads: 0 });
for scanned in 1..=3 {
assert_eq!(wire.poll_line().unwrap(), None);
assert_eq!(wire.poll_scanned, scanned);
assert_eq!(wire.get_mut().reads, scanned);
}
assert_eq!(wire.poll_line().unwrap(), Some(b"abc".to_vec()));
assert_eq!(wire.get_mut().reads, 4);
assert_eq!(wire.poll_scanned, 0);
}
#[test]
fn lines_and_blocks_arrive_in_pieces() {
let mut s = Script::new("first\r\nsecond\nab\r\ncd\r\nlast\r\n");
let mut w = Wire::new(&mut s);
assert_eq!(w.read_line().unwrap(), b"first");
assert_eq!(w.read_line().unwrap(), b"second");
assert_eq!(w.read_block(6).unwrap(), b"ab\r\ncd");
assert_eq!(w.read_block(0).unwrap(), b"");
assert_eq!(w.read_line().unwrap(), b"");
assert_eq!(w.read_line().unwrap(), b"last");
assert!(!w.has_pending());
}
#[test]
fn the_end_of_the_stream_is_an_error() {
let mut s = Script::new("no line ending");
let mut w = Wire::new(&mut s);
assert_eq!(w.read_line(), Err(ProtoError::Io(said!("the server closed the connection"))));
let mut s = Script::new("short");
assert!(matches!(Wire::new(&mut s).read_block(10), Err(ProtoError::Io(_))));
}
#[test]
fn long_lines_and_large_blocks_are_refused() {
let mut s = Script::whole(vec![b'x'; MAX_LINE + CHUNK * 2]);
assert!(matches!(Wire::new(&mut s).read_line(), Err(ProtoError::Protocol(_))));
// A line of exactly the limit is fine.
let mut ok = vec![b'x'; MAX_LINE];
ok.extend_from_slice(b"\r\n");
let mut s = Script::whole(ok);
assert_eq!(Wire::new(&mut s).read_line().unwrap().len(), MAX_LINE);
// The claim alone is refused: nothing is read or allocated.
let mut s = Script::new("");
assert!(matches!(Wire::new(&mut s).read_block(MAX_LITERAL + 1), Err(ProtoError::Protocol(_))));
}
#[test]
fn stream_errors_become_connection_problems() {
let mut w = Wire::new(Broken(ErrorKind::TimedOut));
assert_eq!(w.read_line(), Err(ProtoError::Io(said!("the server took too long to answer"))));
assert!(matches!(w.write(b"x"), Err(ProtoError::Io(_))));
// A stream that is interrupted for ever hangs neither the reader nor the writer.
assert!(matches!(Wire::new(Broken(ErrorKind::Interrupted)).read_line(), Err(ProtoError::Io(_))));
assert!(matches!(Wire::new(Broken(ErrorKind::Interrupted)).write(b"x"), Err(ProtoError::Io(_))));
}
}
+84
View File
@@ -0,0 +1,84 @@
// SPDX-FileCopyrightText: MailCraft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
//! Test streams: a scripted server, and a stream that only fails.
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use std::io::{Error, ErrorKind, Read, Write};
/// A canned server: reads hand out what the server "says" (a few bytes at a time, so every
/// boundary gets split somewhere), writes are kept for the test to look at.
#[derive(Debug)]
pub(crate) struct Script {
input: Vec<u8>,
pos: usize,
step: usize,
trickle: bool,
pub(crate) written: Vec<u8>,
}
impl Script {
/// Hands the bytes out 1–7 at a time.
pub(crate) fn new(server: impl AsRef<[u8]>) -> Script {
Script { input: server.as_ref().to_vec(), pos: 0, step: 0, trickle: true, written: Vec::new() }
}
/// Hands out as much as each read asks for.
pub(crate) fn whole(server: impl AsRef<[u8]>) -> Script {
Script { trickle: false, ..Script::new(server) }
}
/// What the client wrote, as text.
pub(crate) fn sent(&self) -> String {
String::from_utf8_lossy(&self.written).into_owned()
}
/// Whether the client read everything the script had.
pub(crate) fn finished(&self) -> bool {
self.pos >= self.input.len()
}
}
impl Read for Script {
fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
let left = &self.input[self.pos.min(self.input.len())..];
let mut n = left.len().min(buf.len());
if self.trickle {
n = n.min([3, 1, 7, 2, 5, 4, 6][self.step % 7]);
self.step += 1;
}
buf[..n].copy_from_slice(&left[..n]);
self.pos += n;
Ok(n)
}
}
impl Write for Script {
fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
self.written.extend_from_slice(buf);
Ok(buf.len())
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
/// A stream whose every read and write fails.
#[derive(Debug)]
pub(crate) struct Broken(pub(crate) ErrorKind);
impl Read for Broken {
fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
Err(Error::from(self.0))
}
}
impl Write for Broken {
fn write(&mut self, _: &[u8]) -> std::io::Result<usize> {
Err(Error::from(self.0))
}
fn flush(&mut self) -> std::io::Result<()> {
Err(Error::from(self.0))
}
}
+419
View File
@@ -0,0 +1,419 @@
// SPDX-FileCopyrightText: MailCraft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
//! An SMTP client (RFC 5321) with STARTTLS (RFC 3207) and AUTH PLAIN / LOGIN / XOAUTH2 (RFC 4954).
use std::io::{Read, Write};
use base64::{Engine as _, engine::general_purpose::STANDARD};
use crate::i18n::{Arg, Text};
use crate::line::Wire;
use crate::said;
use crate::{ProtoError, Secrets, for_trace, tidy, xoauth2};
/// Most lines one reply may have.
const MAX_REPLY_LINES: usize = 256;
/// Longest command line without its line ending (RFC 5321 §4.5.3.1.4).
const MAX_COMMAND: usize = 510;
/// Longest address (RFC 5321 §4.5.3.1.3 allows 256; some servers take more).
const MAX_ADDRESS: usize = 320;
/// Most recipients one message may have.
const MAX_RECIPIENTS: usize = 10_000;
/// An SMTP session on a stream.
pub struct Smtp<S> {
wire: Wire<S>,
ext: Extensions,
secrets: Secrets,
}
/// What the server offered in its answer to EHLO.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct Extensions {
pub starttls: bool,
pub auth_plain: bool,
pub auth_login: bool,
/// The server takes an OAuth access token instead of a password (SASL XOAUTH2).
pub auth_xoauth2: bool,
/// The largest message the server takes; `Some(0)` when it names no limit.
pub size: Option<u64>,
pub eight_bit_mime: bool,
}
/// Neither the stream nor anything secret is shown.
impl<S> std::fmt::Debug for Smtp<S> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Smtp").field("extensions", &self.ext).finish_non_exhaustive()
}
}
/// One reply: `250-first`, `250 last`.
struct Reply {
code: u16,
lines: Vec<String>,
}
impl Reply {
fn class(&self) -> u16 {
self.code / 100
}
/// `550 5.1.1 No such user`, as the server wrote it.
fn text(&self) -> String {
format!("{} {}", self.code, self.lines.join(" "))
}
}
impl<S: Read + Write> Smtp<S> {
/// Read the 220 greeting.
pub fn connect(stream: S) -> Result<Self, ProtoError> {
let mut smtp = Self::resume(stream);
let greeting = smtp.reply()?;
if greeting.code == 220 { Ok(smtp) } else { Err(smtp.refused(&greeting)) }
}
/// Continue on a stream that already greeted (after the caller wrapped it in TLS).
pub fn resume(stream: S) -> Self {
Smtp { wire: Wire::new(stream), ext: Extensions::default(), secrets: Secrets::default() }
}
/// What the last [`hello`](Self::hello) learned.
pub fn extensions(&self) -> &Extensions {
&self.ext
}
/// The stream the session runs on, for its owner to set up between commands (how long a
/// socket waits, say). Reading from it or writing to it would take the session apart.
pub fn get_mut(&mut self) -> &mut S {
self.wire.get_mut()
}
/// EHLO (falling back to HELO); remembers and returns what the server offers.
pub fn hello(&mut self, client_name: &str) -> Result<Extensions, ProtoError> {
// A name that could break the command line is not sent.
let name = if is_word(client_name) { client_name } else { "localhost" };
let reply = self.command(&format!("EHLO {name}"))?;
if reply.code == 250 {
self.ext = extensions(&reply.lines);
return Ok(self.ext.clone());
}
if reply.class() != 5 {
return Err(self.refused(&reply));
}
// A server from before 1995 (or one hiding its extensions).
let reply = self.command(&format!("HELO {name}"))?;
if reply.code != 250 {
return Err(self.refused(&reply));
}
self.ext = Extensions::default();
Ok(self.ext.clone())
}
/// Send STARTTLS and hand the stream back for the caller to wrap; call `resume` + `hello` afterwards.
pub fn starttls(mut self) -> Result<S, ProtoError> {
let reply = self.command("STARTTLS")?;
if reply.code != 220 {
return Err(self.refused(&reply));
}
// Anything after the go-ahead was slipped in before encryption started (RFC 3207 §6).
if self.wire.has_pending() {
return Err(ProtoError::Protocol(said!("the server sent data before the secure connection started")));
}
Ok(self.wire.into_inner())
}
/// AUTH PLAIN when offered, else AUTH LOGIN. 535 and friends → `ProtoError::Auth`.
pub fn auth(&mut self, user: &str, password: &str) -> Result<(), ProtoError> {
if user.contains('\0') || password.contains('\0') {
return Err(ProtoError::Auth(said!("the user name or password has a character that can't be sent")));
}
self.secrets.add(password);
if self.ext.auth_plain {
let payload = STANDARD.encode(format!("\0{user}\0{password}"));
self.secrets.add(&payload);
let line = format!("AUTH PLAIN {payload}");
let reply = if line.len() <= MAX_COMMAND {
self.secret_command(&line, "AUTH PLAIN ***")?
} else {
// Too long for one line: wait for the server to ask (RFC 4954 §4).
let ask = self.command("AUTH PLAIN")?;
if ask.code != 334 {
return Err(self.sign_in_failed(&ask));
}
self.secret_command(&payload, "***")?
};
return self.signed_in(&reply);
}
if self.ext.auth_login {
let ask = self.command("AUTH LOGIN")?;
if ask.code != 334 {
return Err(self.sign_in_failed(&ask));
}
let ask = self.secret_command(&STANDARD.encode(user), "***")?;
if ask.code != 334 {
return Err(self.sign_in_failed(&ask));
}
let encoded = STANDARD.encode(password);
self.secrets.add(&encoded);
let reply = self.secret_command(&encoded, "***")?;
return self.signed_in(&reply);
}
Err(ProtoError::Auth(said!("the server offers no way to sign in with a password")))
}
/// AUTH XOAUTH2: an OAuth access token in place of a password. A server that doesn't offer
/// it isn't shown the token. 535 and friends → `ProtoError::Auth`.
pub fn auth_xoauth2(&mut self, user: &str, token: &str) -> Result<(), ProtoError> {
let payload = xoauth2(user, token)?;
if !self.ext.auth_xoauth2 {
return Err(ProtoError::Auth(said!("the server offers no way to sign in with an access token")));
}
self.secrets.add(token);
self.secrets.add(&payload);
let line = format!("AUTH XOAUTH2 {payload}");
let reply = if line.len() <= MAX_COMMAND {
self.secret_command(&line, "AUTH XOAUTH2 ***")?
} else {
// Too long for one line, as tokens mostly are: wait for the server to ask (RFC 4954 §4).
let ask = self.command("AUTH XOAUTH2")?;
if ask.code != 334 {
return Err(self.sign_in_failed(&ask));
}
self.secret_command(&payload, "***")?
};
match reply.code {
235 => Ok(()),
334 => {
// A refusal comes in two parts: the reasons (JSON in base64), and, once an empty
// line has acknowledged them, the verdict.
let verdict = self.command("")?;
match verdict.code {
235 => Ok(()),
334 => {
let _ = self.command("*");
Err(ProtoError::Auth(said!("the server asked for more than a user name and access token")))
}
_ => Err(self.sign_in_failed(&verdict)),
}
}
_ => Err(self.sign_in_failed(&reply)),
}
}
/// MAIL FROM, RCPT TO (every recipient must be accepted), DATA with CRLF normalisation and dot-stuffing.
pub fn send(&mut self, from: &str, recipients: &[&str], message: &[u8]) -> Result<(), ProtoError> {
// Nothing is sent unless every address is safe to put on a command line.
if !from.is_empty() && !is_address(from) {
return Err(bad_address(from));
}
if recipients.is_empty() {
return Err(ProtoError::Protocol(said!("the message has no recipients")));
}
if recipients.len() > MAX_RECIPIENTS {
return Err(ProtoError::Protocol(said!("the message has too many recipients")));
}
if let Some(bad) = recipients.iter().find(|r| !is_address(r)) {
return Err(bad_address(bad));
}
let (data, size) = data_block(message);
let mut mail = format!("MAIL FROM:<{from}>");
if self.ext.size.is_some() {
mail.push_str(&format!(" SIZE={size}"));
}
if self.ext.eight_bit_mime && !message.is_ascii() {
mail.push_str(" BODY=8BITMIME");
}
let reply = self.command(&mail)?;
if reply.class() != 2 {
return Err(self.refused(&reply));
}
for rcpt in recipients {
let reply = self.command(&format!("RCPT TO:<{rcpt}>"))?;
if reply.class() != 2 {
let refused = match self.refused(&reply) {
// (The address, then what the server said of it: no words of MailCraft's to say.)
ProtoError::Rejected(text) => {
ProtoError::Rejected(Text::new("{rcpt}: {text}", vec![("rcpt", Arg::Plain(rcpt.to_string())), ("text", Arg::said(text))]))
}
other => other,
};
return Err(self.give_up(refused));
}
}
let reply = self.command("DATA")?;
if reply.code != 354 {
let refused = self.refused(&reply);
return Err(self.give_up(refused));
}
log::trace!("C: ({size} bytes)");
self.wire.write(&data)?;
self.wire.flush()?;
let reply = self.reply()?;
if reply.class() != 2 {
return Err(self.refused(&reply));
}
Ok(())
}
/// QUIT. A server that hangs up without answering has quit all the same.
pub fn quit(mut self) -> Result<(), ProtoError> {
match self.command("QUIT") {
Ok(reply) if reply.class() == 2 => Ok(()),
Ok(reply) => Err(self.refused(&reply)),
// A server that hangs up instead of saying goodbye has quit all the same.
Err(ProtoError::Io(_)) => Ok(()),
Err(e) => Err(e),
}
}
/// Forget the message being composed, so the session can go on; hands the error back.
fn give_up(&mut self, error: ProtoError) -> ProtoError {
let _ = self.command("RSET");
error
}
fn command(&mut self, line: &str) -> Result<Reply, ProtoError> {
self.secret_command(line, line)
}
/// Send `line`; the log gets `shown` instead.
fn secret_command(&mut self, line: &str, shown: &str) -> Result<Reply, ProtoError> {
log::trace!("C: {}", for_trace(&self.secrets.hide(shown)));
let mut out = Vec::with_capacity(line.len() + 2);
out.extend_from_slice(line.as_bytes());
out.extend_from_slice(b"\r\n");
self.wire.write(&out)?;
self.wire.flush()?;
self.reply()
}
fn reply(&mut self) -> Result<Reply, ProtoError> {
let mut reply = Reply { code: 0, lines: Vec::new() };
for n in 0..MAX_REPLY_LINES {
let raw = self.wire.read_line()?;
let line = String::from_utf8_lossy(&raw);
log::trace!("S: {}", for_trace(&self.secrets.hide(&line)));
// Three digits, then `-` (more lines follow), a space or nothing (the last line).
let code = line.get(..3).filter(|d| d.bytes().all(|b| b.is_ascii_digit())).and_then(|d| d.parse::<u16>().ok());
let rest = line.get(3..).unwrap_or("");
let more = match (code, rest.chars().next()) {
(Some(code), Some('-')) if n == 0 || code == reply.code => true,
(Some(code), Some(' ') | None) if n == 0 || code == reply.code => false,
_ => return Err(ProtoError::Protocol(said!("\"{line}\" is not an SMTP reply", line = tidy(&self.secrets.hide(&line))))),
};
reply.code = code.unwrap_or(0);
reply.lines.push(rest.get(1..).unwrap_or("").to_string());
if !more {
return Ok(reply);
}
}
Err(ProtoError::Protocol(said!("the server's reply has too many lines")))
}
/// The error for a reply that isn't the one hoped for.
fn refused(&self, reply: &Reply) -> ProtoError {
// Hidden before it is shortened: a secret cut in half would no longer be recognised.
let text = tidy(&self.secrets.hide(&reply.text()));
if matches!(reply.class(), 4 | 5) { ProtoError::Rejected(text.into()) } else { ProtoError::Protocol(text.into()) }
}
fn sign_in_failed(&mut self, reply: &Reply) -> ProtoError {
match self.refused(reply) {
ProtoError::Rejected(text) => ProtoError::Auth(text),
other => other,
}
}
fn signed_in(&mut self, reply: &Reply) -> Result<(), ProtoError> {
match reply.code {
235 => Ok(()),
334 => {
// Another question we have no answer to: cancel the exchange (RFC 4954 §4).
let _ = self.command("*");
Err(ProtoError::Auth(said!("the server asked for more than a user name and password")))
}
_ => Err(self.sign_in_failed(reply)),
}
}
}
/// The extensions named in an EHLO reply (its first line is the server's name).
fn extensions(lines: &[String]) -> Extensions {
let mut ext = Extensions::default();
for line in lines.iter().skip(1) {
let upper = line.to_ascii_uppercase();
// `AUTH=PLAIN LOGIN` is how some old servers spell `AUTH PLAIN LOGIN`.
let mut words = upper.split([' ', '\t', '=']).filter(|w| !w.is_empty());
match words.next() {
Some("STARTTLS") => ext.starttls = true,
Some("8BITMIME") => ext.eight_bit_mime = true,
Some("SIZE") => ext.size = Some(words.next().and_then(|n| n.parse().ok()).unwrap_or(0)),
Some("AUTH") => {
for mechanism in words {
match mechanism {
"PLAIN" => ext.auth_plain = true,
"LOGIN" => ext.auth_login = true,
"XOAUTH2" => ext.auth_xoauth2 = true,
_ => {}
}
}
}
_ => {}
}
}
ext
}
/// Visible ASCII without spaces: safe as one word of a command line.
fn is_word(s: &str) -> bool {
!s.is_empty() && s.len() <= 255 && s.bytes().all(|b| b.is_ascii_graphic())
}
/// An address that can go between `<` and `>` as it is.
fn is_address(s: &str) -> bool {
is_word(s) && s.len() <= MAX_ADDRESS && !s.contains(['<', '>'])
}
fn bad_address(address: &str) -> ProtoError {
ProtoError::Protocol(said!("\"{address}\" can't be used as an address", address = tidy(address)))
}
/// The message as DATA wants it: every line ending CRLF, a leading dot doubled, the closing
/// `.` line added. Also returns the size without the added dots and closing line (RFC 1870).
fn data_block(message: &[u8]) -> (Vec<u8>, usize) {
let mut out = Vec::with_capacity(message.len().saturating_add(message.len() / 32).saturating_add(8));
let mut dots = 0usize;
let mut line_start = true;
let mut bytes = message.iter().copied().peekable();
while let Some(b) = bytes.next() {
match b {
b'\r' => {
bytes.next_if_eq(&b'\n');
out.extend_from_slice(b"\r\n");
line_start = true;
}
b'\n' => {
out.extend_from_slice(b"\r\n");
line_start = true;
}
b'.' if line_start => {
out.extend_from_slice(b"..");
dots += 1;
line_start = false;
}
_ => {
out.push(b);
line_start = false;
}
}
}
if !line_start {
out.extend_from_slice(b"\r\n");
}
let size = out.len().saturating_sub(dots);
out.extend_from_slice(b".\r\n");
(out, size)
}
#[cfg(test)]
mod tests;
+455
View File
@@ -0,0 +1,455 @@
// SPDX-FileCopyrightText: MailCraft contributors
// SPDX-License-Identifier: MIT OR Apache-2.0
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use std::io::ErrorKind;
use proptest::prelude::*;
use super::*;
use crate::script::{Broken, Script};
const EHLO: &str =
"250-mail.example.org greets you\r\n250-SIZE 35882577\r\n250-8BITMIME\r\n250-STARTTLS\r\n250-AUTH LOGIN PLAIN XOAUTH2\r\n250 HELP\r\n";
fn rejected(r: Result<(), ProtoError>) -> String {
match r {
Err(ProtoError::Rejected(text)) => text.to_string(),
other => panic!("expected a rejection, got {other:?}"),
}
}
#[test]
fn a_whole_session() {
let mut s = Script::new(format!(
"220-mail.example.org ESMTP\r\n220 ready\r\n{EHLO}235 2.7.0 Accepted\r\n250 OK\r\n250 OK\r\n251 will forward\r\n354 go ahead\r\n250 queued as 1\r\n221 bye\r\n"
));
let mut smtp = Smtp::connect(&mut s).unwrap();
let ext = smtp.hello("[127.0.0.1]").unwrap();
assert_eq!(
ext,
Extensions { starttls: true, auth_plain: true, auth_login: true, auth_xoauth2: true, size: Some(35_882_577), eight_bit_mime: true }
);
assert_eq!(smtp.extensions(), &ext);
smtp.auth("ada@example.org", "hunter2").unwrap();
smtp.send("ada@example.org", &["bob@example.org", "carol@example.org"], b"Subject: Hi\r\n\r\nHello.\r\n").unwrap();
smtp.quit().unwrap();
assert!(s.finished());
assert_eq!(
s.sent(),
"EHLO [127.0.0.1]\r\n\
AUTH PLAIN AGFkYUBleGFtcGxlLm9yZwBodW50ZXIy\r\n\
MAIL FROM:<ada@example.org> SIZE=23\r\n\
RCPT TO:<bob@example.org>\r\n\
RCPT TO:<carol@example.org>\r\n\
DATA\r\n\
Subject: Hi\r\n\r\nHello.\r\n.\r\n\
QUIT\r\n"
);
}
#[test]
fn the_plain_payload_is_nul_user_nul_password() {
let mut s = Script::new("250-x\r\n250 AUTH PLAIN\r\n235 ok\r\n");
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
smtp.auth("grace", "pässword \"1\"").unwrap();
let sent = s.sent();
let payload = sent.lines().nth(1).unwrap().strip_prefix("AUTH PLAIN ").unwrap();
assert_eq!(STANDARD.decode(payload).unwrap(), "\0grace\0pässword \"1\"".as_bytes());
}
#[test]
fn a_long_plain_payload_waits_for_the_server_to_ask() {
let mut s = Script::new("250-x\r\n250 AUTH PLAIN\r\n334 \r\n235 ok\r\n");
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
let password = "p".repeat(600);
smtp.auth("grace", &password).unwrap();
let sent = s.sent();
let lines: Vec<&str> = sent.lines().collect();
assert_eq!(lines[1], "AUTH PLAIN");
assert_eq!(STANDARD.decode(lines[2]).unwrap(), format!("\0grace\0{password}").as_bytes());
}
#[test]
fn login_is_used_when_plain_is_not_offered() {
let mut s = Script::new("250-x\r\n250 AUTH=LOGIN CRAM-MD5\r\n334 VXNlcm5hbWU6\r\n334 UGFzc3dvcmQ6\r\n235 ok\r\n");
let mut smtp = Smtp::resume(&mut s);
let ext = smtp.hello("localhost").unwrap();
assert!(ext.auth_login && !ext.auth_plain);
smtp.auth("ada", "hunter2").unwrap();
assert_eq!(s.sent(), "EHLO localhost\r\nAUTH LOGIN\r\nYWRh\r\naHVudGVyMg==\r\n");
}
#[test]
fn a_wrong_password_is_an_auth_error_that_never_shows_it() {
// A careless server repeats what it was sent.
let echo = "535-5.7.8 no such password: hunter2\r\n535 5.7.8 (AGFkYQBodW50ZXIy)\r\n";
let mut s = Script::new(format!("250-x\r\n250 AUTH PLAIN\r\n{echo}"));
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
let err = smtp.auth("ada", "hunter2").unwrap_err();
assert_eq!(err, ProtoError::Auth("535 5.7.8 no such password: *** 5.7.8 (***)".into()));
assert!(!format!("{err} {err:?} {smtp:?}").contains("hunter2"));
// The same over LOGIN, where the password travels alone.
let mut s = Script::new("250-x\r\n250 AUTH LOGIN\r\n334 VXNlcm5hbWU6\r\n334 UGFzc3dvcmQ6\r\n535 bad aHVudGVyMg== / hunter2\r\n");
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
assert_eq!(smtp.auth("ada", "hunter2"), Err(ProtoError::Auth("535 bad *** / ***".into())));
}
#[test]
fn sign_in_needs_a_method_and_sendable_text() {
let mut s = Script::new("250-x\r\n250 AUTH XOAUTH2\r\n");
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
assert!(matches!(smtp.auth("ada", "hunter2"), Err(ProtoError::Auth(_))));
assert!(matches!(smtp.auth("ada", "hun\0ter2"), Err(ProtoError::Auth(_))));
// Neither attempt put anything on the wire.
assert_eq!(s.sent(), "EHLO localhost\r\n");
}
/// What an XOAUTH2 response says under its base64.
fn bearer(payload: &str) -> String {
String::from_utf8(STANDARD.decode(payload).unwrap()).unwrap()
}
#[test]
fn a_token_signs_in_with_xoauth2() {
let mut s = Script::new("250-x\r\n250 AUTH LOGIN XOAUTH2\r\n235 2.7.0 Authentication successful\r\n");
let mut smtp = Smtp::resume(&mut s);
assert!(smtp.hello("localhost").unwrap().auth_xoauth2);
smtp.auth_xoauth2("ada@example.org", "tok.en-123").unwrap();
assert!(s.finished());
let sent = s.sent();
let lines: Vec<&str> = sent.lines().collect();
assert_eq!(lines.len(), 2);
assert_eq!(bearer(lines[1].strip_prefix("AUTH XOAUTH2 ").unwrap()), "user=ada@example.org\x01auth=Bearer tok.en-123\x01\x01");
}
#[test]
fn a_long_token_waits_for_the_server_to_ask() {
// Real tokens run to a couple of thousand characters.
let token = "t".repeat(2_000);
let mut s = Script::new("250-x\r\n250 AUTH XOAUTH2\r\n334 \r\n235 ok\r\n");
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
smtp.auth_xoauth2("ada@example.org", &token).unwrap();
let sent = s.sent();
let lines: Vec<&str> = sent.lines().collect();
assert_eq!(lines[1], "AUTH XOAUTH2");
assert_eq!(bearer(lines[2]), format!("user=ada@example.org\x01auth=Bearer {token}\x01\x01"));
// The longest that still fits goes in one line.
let token = "t".repeat(349);
let mut s = Script::new("250-x\r\n250 AUTH XOAUTH2\r\n235 ok\r\n");
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
smtp.auth_xoauth2("ada", &token).unwrap();
let sent = s.sent();
assert_eq!((sent.lines().count(), sent.lines().nth(1).unwrap().len()), (2, MAX_COMMAND - 1));
// A server that won't ask is not shown the token.
let token = "t".repeat(2_000);
let mut s = Script::new("250-x\r\n250 AUTH XOAUTH2\r\n504 5.5.4 not that way\r\n");
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
assert_eq!(smtp.auth_xoauth2("ada", &token), Err(ProtoError::Auth("504 5.5.4 not that way".into())));
assert_eq!(s.sent(), "EHLO localhost\r\nAUTH XOAUTH2\r\n");
}
#[test]
fn a_refused_token_is_an_auth_error_that_never_shows_it() {
let payload = xoauth2("ada", "tok.en-123").unwrap();
let reasons = STANDARD.encode(r#"{"status":"401","schemes":"bearer","scope":"https://mail.example.org/"}"#);
// The reasons come first and the verdict after an empty line; a careless server repeats what it was sent.
let mut s = Script::new(format!("250-x\r\n250 AUTH XOAUTH2\r\n334 {reasons}\r\n535-5.7.3 no good: tok.en-123\r\n535 5.7.3 ({payload})\r\n"));
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
let err = smtp.auth_xoauth2("ada", "tok.en-123").unwrap_err();
assert_eq!(err, ProtoError::Auth("535 5.7.3 no good: *** 5.7.3 (***)".into()));
assert!(!format!("{err} {err:?} {smtp:?}").contains("tok.en-123"));
assert_eq!(s.sent(), format!("EHLO localhost\r\nAUTH XOAUTH2 {payload}\r\n\r\n"));
assert!(s.finished());
// The same when the token went on a line of its own.
let token = "t".repeat(2_000);
let mut s = Script::new(format!("250-x\r\n250 AUTH XOAUTH2\r\n334 \r\n334 {reasons}\r\n535 5.7.3 Authentication unsuccessful\r\n"));
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
assert_eq!(smtp.auth_xoauth2("ada", &token), Err(ProtoError::Auth("535 5.7.3 Authentication unsuccessful".into())));
assert_eq!(s.sent(), format!("EHLO localhost\r\nAUTH XOAUTH2\r\n{}\r\n\r\n", xoauth2("ada", &token).unwrap()));
assert!(s.finished());
// Refused in one word, without reasons.
let mut s = Script::new("250-x\r\n250 AUTH XOAUTH2\r\n535 5.7.3 Authentication unsuccessful\r\n");
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
assert_eq!(smtp.auth_xoauth2("ada", "tok.en-123"), Err(ProtoError::Auth("535 5.7.3 Authentication unsuccessful".into())));
assert_eq!(s.sent(), format!("EHLO localhost\r\nAUTH XOAUTH2 {payload}\r\n"));
// A question after the reasons has no answer: the exchange is cancelled.
let mut s = Script::new(format!("250-x\r\n250 AUTH XOAUTH2\r\n334 {reasons}\r\n334 more?\r\n501 cancelled\r\n"));
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
assert!(matches!(smtp.auth_xoauth2("ada", "tok.en-123"), Err(ProtoError::Auth(_))));
assert!(s.sent().ends_with("\r\n\r\n*\r\n"));
}
#[test]
fn a_token_echoed_in_a_long_reply_is_hidden_whole() {
// The reply is shortened for the error text: not before the token is out of it.
let token = format!("head.{}.tail", "x".repeat(2_000));
let mut s = Script::new(format!("250-x\r\n250 AUTH XOAUTH2\r\n334 \r\n535 5.7.3 {} bad token {token}\r\n", "no ".repeat(80)));
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
let err = smtp.auth_xoauth2("ada", &token).unwrap_err();
let shown = format!("{err} {err:?}");
assert!(matches!(err, ProtoError::Auth(_)));
assert!(!shown.contains("head.") && !shown.contains("xxxx"), "{shown}");
}
#[test]
fn a_token_needs_a_server_that_takes_one_and_sendable_text() {
let mut s = Script::new("250-x\r\n250 AUTH PLAIN LOGIN\r\n");
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
assert_eq!(smtp.auth_xoauth2("ada", "tok.en-123"), Err(ProtoError::Auth(said!("the server offers no way to sign in with an access token"))));
assert_eq!(s.sent(), "EHLO localhost\r\n");
let mut s = Script::new("250-x\r\n250 AUTH XOAUTH2\r\n235 ok\r\n");
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
for (user, token) in
[("ada", ""), ("ada", "tok\r\nQUIT"), ("ada", "tok\x01"), ("ada\x01auth=Bearer x", "tok"), ("a\0da", "tok"), ("ada\n", "tok")]
{
assert!(matches!(smtp.auth_xoauth2(user, token), Err(ProtoError::Auth(_))), "{user:?} {token:?}");
}
assert_eq!(s.sent(), "EHLO localhost\r\n");
}
#[test]
fn an_unexpected_second_question_cancels_the_sign_in() {
let mut s = Script::new("250-x\r\n250 AUTH PLAIN\r\n334 more?\r\n501 cancelled\r\n");
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
assert!(matches!(smtp.auth("ada", "hunter2"), Err(ProtoError::Auth(_))));
assert!(s.sent().ends_with("\r\n*\r\n"));
}
#[test]
fn helo_is_the_fallback() {
let mut s = Script::new("220 old.example.org\r\n502 what?\r\n250 old.example.org\r\n");
let mut smtp = Smtp::connect(&mut s).unwrap();
assert_eq!(smtp.hello("localhost").unwrap(), Extensions::default());
assert_eq!(s.sent(), "EHLO localhost\r\nHELO localhost\r\n");
// A server on its way out is not asked twice.
let mut s = Script::new("421 shutting down\r\n");
assert_eq!(Smtp::resume(&mut s).hello("localhost"), Err(ProtoError::Rejected("421 shutting down".into())));
assert_eq!(s.sent(), "EHLO localhost\r\n");
}
#[test]
fn a_client_name_that_could_break_the_line_is_replaced() {
for bad in ["", "two words", "evil\r\nMAIL FROM:<x>", "nön-ascii"] {
let mut s = Script::new("250 ok\r\n");
Smtp::resume(&mut s).hello(bad).unwrap();
assert_eq!(s.sent(), "EHLO localhost\r\n", "{bad:?}");
}
}
#[test]
fn extensions_are_read_whatever_their_case() {
let mut s = Script::new("250-x\r\n250-starttls\r\n250-Size\r\n250-auth plain\r\n250 8bitmime\r\n");
let ext = Smtp::resume(&mut s).hello("localhost").unwrap();
assert_eq!(ext, Extensions { starttls: true, auth_plain: true, auth_login: false, auth_xoauth2: false, size: Some(0), eight_bit_mime: true });
let mut s = Script::new("250-x\r\n250 auth=login xoauth2 OAUTHBEARER\r\n");
let ext = Smtp::resume(&mut s).hello("localhost").unwrap();
assert_eq!(ext, Extensions { auth_login: true, auth_xoauth2: true, ..Default::default() });
}
#[test]
fn starttls_hands_the_stream_back() {
let mut s = Script::new("220 hi\r\n250-x\r\n250 STARTTLS\r\n220 go ahead\r\n");
let mut smtp = Smtp::connect(&mut s).unwrap();
assert!(smtp.hello("localhost").unwrap().starttls);
let stream = smtp.starttls().unwrap();
assert_eq!(stream.sent(), "EHLO localhost\r\nSTARTTLS\r\n");
let mut s = Script::new("454 TLS not available\r\n");
assert_eq!(Smtp::resume(&mut s).starttls().unwrap_err(), ProtoError::Rejected("454 TLS not available".into()));
}
#[test]
fn text_slipped_in_before_tls_is_refused() {
// Both lines arrive in one read, as an attacker in the middle would send them.
let mut s = Script::whole("220 go ahead\r\n250 injected\r\n");
assert!(matches!(Smtp::resume(&mut s).starttls(), Err(ProtoError::Protocol(_))));
}
#[test]
fn data_is_normalised_and_dot_stuffed() {
let message = b"Subject: dots\n\n.leading\r\n..two\rbare CR\n.\nno dot. here\n\nlast line without an ending";
let mut s = Script::new("250 ok\r\n250 ok\r\n354 go\r\n250 ok\r\n");
let mut smtp = Smtp::resume(&mut s);
smtp.send("ada@example.org", &["bob@example.org"], message).unwrap();
let sent = s.sent();
let data = sent.split_once("DATA\r\n").unwrap().1;
assert_eq!(data, "Subject: dots\r\n\r\n..leading\r\n...two\r\nbare CR\r\n..\r\nno dot. here\r\n\r\nlast line without an ending\r\n.\r\n");
// No SIZE or BODY parameter for a server that didn't offer them.
assert!(sent.starts_with("MAIL FROM:<ada@example.org>\r\n"));
}
#[test]
fn data_blocks() {
assert_eq!(data_block(b""), (b".\r\n".to_vec(), 0));
assert_eq!(data_block(b"a"), (b"a\r\n.\r\n".to_vec(), 3));
assert_eq!(data_block(b"."), (b"..\r\n.\r\n".to_vec(), 3));
assert_eq!(data_block(b"\r\r\n\n"), (b"\r\n\r\n\r\n.\r\n".to_vec(), 6));
assert_eq!(data_block(b"a\r"), (b"a\r\n.\r\n".to_vec(), 3));
}
#[test]
fn eight_bit_mail_says_so_when_the_server_takes_it() {
let mut s = Script::new("250-x\r\n250 8BITMIME\r\n250 ok\r\n250 ok\r\n354 go\r\n250 ok\r\n250 ok\r\n250 ok\r\n354 go\r\n250 ok\r\n");
let mut smtp = Smtp::resume(&mut s);
smtp.hello("localhost").unwrap();
smtp.send("ada@example.org", &["bob@example.org"], "Subject: é\r\n\r\n".as_bytes()).unwrap();
smtp.send("", &["bob@example.org"], b"Subject: e\r\n\r\n").unwrap();
let sent = s.sent();
assert!(sent.contains("MAIL FROM:<ada@example.org> BODY=8BITMIME\r\n"));
// An empty sender is the bounce address.
assert!(sent.contains("MAIL FROM:<>\r\n"));
}
#[test]
fn a_refused_recipient_stops_the_message_and_resets() {
let mut s = Script::new("250 ok\r\n250 ok\r\n550 5.1.1 no such user\r\n250 reset\r\n");
let mut smtp = Smtp::resume(&mut s);
let text = rejected(smtp.send("ada@example.org", &["bob@example.org", "nobody@example.org", "carol@example.org"], b"x"));
assert_eq!(text, "nobody@example.org: 550 5.1.1 no such user");
assert!(s.sent().ends_with("RCPT TO:<nobody@example.org>\r\nRSET\r\n"));
}
#[test]
fn refusals_at_each_step() {
// MAIL FROM.
let mut s = Script::new("552 5.3.4 too big\r\n");
assert_eq!(rejected(Smtp::resume(&mut s).send("a@example.org", &["b@example.org"], b"x")), "552 5.3.4 too big");
// DATA.
let mut s = Script::new("250 ok\r\n250 ok\r\n554 no\r\n250 reset\r\n");
assert_eq!(rejected(Smtp::resume(&mut s).send("a@example.org", &["b@example.org"], b"x")), "554 no");
assert!(s.sent().ends_with("DATA\r\nRSET\r\n"));
// After the message.
let mut s = Script::new("250 ok\r\n250 ok\r\n354 go\r\n451 4.3.0 try later\r\n");
assert_eq!(rejected(Smtp::resume(&mut s).send("a@example.org", &["b@example.org"], b"x")), "451 4.3.0 try later");
// The greeting.
let mut s = Script::new("554 no service for you\r\n");
assert_eq!(Smtp::connect(&mut s).unwrap_err(), ProtoError::Rejected("554 no service for you".into()));
}
#[test]
fn unsafe_addresses_are_never_sent() {
let cases: [(&str, &[&str]); 6] = [
("ada@example.org", &[]),
("ada@example.org", &["bob@example.org>\r\nRCPT TO:<eve@example.org"]),
("ada@example.org", &["bob smith@example.org"]),
("ada@example.org", &[""]),
("ada@example.org\r\nDATA", &["bob@example.org"]),
("ada@example.org", &["bøb@example.org"]),
];
for (from, to) in cases {
let mut s = Script::new("250 ok\r\n250 ok\r\n354 go\r\n250 ok\r\n");
assert!(matches!(Smtp::resume(&mut s).send(from, to, b"x"), Err(ProtoError::Protocol(_))), "{from:?} {to:?}");
assert_eq!(s.sent(), "", "{from:?} {to:?}");
}
}
#[test]
fn junk_replies_are_protocol_errors() {
for junk in ["hello there\r\n", "25 ok\r\n", "250ok\r\n", "250-first\r\n251 second\r\n", "\r\n", "2éé ok\r\n"] {
let mut s = Script::new(junk);
assert!(matches!(Smtp::resume(&mut s).hello("localhost"), Err(ProtoError::Protocol(_))), "{junk:?}");
}
// A reply that never ends.
let mut s = Script::whole("250-more\r\n".repeat(MAX_REPLY_LINES + 1));
assert_eq!(Smtp::resume(&mut s).hello("localhost"), Err(ProtoError::Protocol(said!("the server's reply has too many lines"))));
// A greeting that is a success code but not 220.
let mut s = Script::new("250 hello\r\n");
assert!(matches!(Smtp::connect(&mut s), Err(ProtoError::Protocol(_))));
}
#[test]
fn a_dead_connection_is_an_io_error() {
let mut s = Script::new("250-half a rep");
assert_eq!(Smtp::resume(&mut s).hello("localhost"), Err(ProtoError::Io(said!("the server closed the connection"))));
assert!(matches!(Smtp::connect(Broken(ErrorKind::TimedOut)), Err(ProtoError::Io(_))));
assert!(matches!(Smtp::resume(Broken(ErrorKind::ConnectionReset)).send("a@example.org", &["b@example.org"], b"x"), Err(ProtoError::Io(_))));
}
#[test]
fn quitting() {
let mut s = Script::new("221 bye\r\n");
assert_eq!(Smtp::resume(&mut s).quit(), Ok(()));
// A server that just hangs up has quit too.
let mut s = Script::new("");
assert_eq!(Smtp::resume(&mut s).quit(), Ok(()));
assert_eq!(s.sent(), "QUIT\r\n");
let mut s = Script::new("500 what\r\n");
assert!(matches!(Smtp::resume(&mut s).quit(), Err(ProtoError::Rejected(_))));
}
/// Everything a client does, against whatever the "server" says.
fn drive(server: &[u8]) {
let mut s = Script::new(server);
if let Ok(mut smtp) = Smtp::connect(&mut s) {
let _ = smtp.hello("localhost");
let _ = smtp.auth("ada@example.org", "hunter2");
let _ = smtp.send("ada@example.org", &["bob@example.org"], b"Subject: x\r\n\r\n.\r\n");
let _ = smtp.quit();
}
let mut s = Script::new(server);
let mut smtp = Smtp::resume(&mut s);
smtp.ext = Extensions { auth_login: true, ..Default::default() };
let _ = smtp.auth("ada", "hunter2");
let _ = smtp.starttls();
// With a token, on one line and on its own.
for token in ["tok.en-123".to_string(), "t".repeat(700)] {
let mut s = Script::new(server);
let mut smtp = Smtp::resume(&mut s);
smtp.ext = Extensions { auth_xoauth2: true, ..Default::default() };
let _ = smtp.auth_xoauth2("ada@example.org", &token);
let _ = smtp.send("ada@example.org", &["bob@example.org"], b"x");
}
}
proptest! {
#[test]
fn arbitrary_server_bytes_never_panic_or_hang(server in proptest::collection::vec(any::<u8>(), 0..600)) {
drive(&server);
}
#[test]
fn reply_shaped_noise_never_panics(lines in proptest::collection::vec(("[0-9]{3}", "[- ]?", "[ -~]{0,30}"), 0..40)) {
let server: String = lines.iter().map(|(code, sep, text)| format!("{code}{sep}{text}\r\n")).collect();
drive(server.as_bytes());
}
#[test]
fn data_blocks_never_end_early(message in proptest::collection::vec(prop_oneof![Just(b'.'), Just(b'\r'), Just(b'\n'), any::<u8>()], 0..300)) {
let (data, size) = data_block(&message);
prop_assert!(data.ends_with(b".\r\n"));
let body = &data[..data.len() - 3];
prop_assert!(body.is_empty() || body.ends_with(b"\r\n"));
// No bare CR or LF, and no line that is just a dot before the end.
let text = String::from_utf8_lossy(body);
prop_assert_eq!(body.iter().filter(|b| **b == b'\r').count(), body.iter().filter(|b| **b == b'\n').count());
prop_assert!(!text.contains("\r\n.\r\n") && !text.starts_with(".\r\n"));
prop_assert_eq!(body.windows(2).filter(|w| w[0] == b'\r' && w[1] == b'\n').count(), body.iter().filter(|b| **b == b'\n').count());
// Taking the stuffing out gives the size that was announced.
let unstuffed: usize = body.split_inclusive(|b| *b == b'\n').map(|l| l.len() - usize::from(l.starts_with(b"."))).sum();
prop_assert_eq!(unstuffed, size);
}
}