diff --git a/Cargo.lock b/Cargo.lock index 4eea31faf..27fc4016c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -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" diff --git a/Cargo.toml b/Cargo.toml index 3c701ab6b..178381cce 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -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- = { path = "crates/" }` diff --git a/crates/proto/Cargo.toml b/crates/proto/Cargo.toml new file mode 100644 index 000000000..528e407a8 --- /dev/null +++ b/crates/proto/Cargo.toml @@ -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 } diff --git a/crates/proto/src/i18n.rs b/crates/proto/src/i18n.rs new file mode 100644 index 000000000..af0499154 --- /dev/null +++ b/crates/proto/src/i18n.rs @@ -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 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 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"); + } +} diff --git a/crates/proto/src/imap/gmail_labels_tests.rs b/crates/proto/src/imap/gmail_labels_tests.rs new file mode 100644 index 000000000..441e3220b --- /dev/null +++ b/crates/proto/src/imap/gmail_labels_tests.rs @@ -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>)> { + 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> { + 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>)> = 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::(), 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::(), 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::>(), [(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 = (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); +} diff --git a/crates/proto/src/imap/gmail_tests.rs b/crates/proto/src/imap/gmail_tests.rs new file mode 100644 index 000000000..451690bc5 --- /dev/null +++ b/crates/proto/src/imap/gmail_tests.rs @@ -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)> = 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(_)))); +} diff --git a/crates/proto/src/imap/idle.rs b/crates/proto/src/imap/idle.rs new file mode 100644 index 000000000..ecccec50c --- /dev/null +++ b/crates/proto/src/imap/idle.rs @@ -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 { + 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::().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 Imap { + /// 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, 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, 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") + } +} diff --git a/crates/proto/src/imap/idle_tests.rs b/crates/proto/src/imap/idle_tests.rs new file mode 100644 index 000000000..cb0515cdd --- /dev/null +++ b/crates/proto/src/imap/idle_tests.rs @@ -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, 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::(), 0..800), greeted in any::()) { + 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(_)) }); + } +} diff --git a/crates/proto/src/imap/limits_tests.rs b/crates/proto/src/imap/limits_tests.rs new file mode 100644 index 000000000..9b802055c --- /dev/null +++ b/crates/proto/src/imap/limits_tests.rs @@ -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 = (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::()).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::>(), [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::(), 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::() + + "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())); + } +} diff --git a/crates/proto/src/imap/mod.rs b/crates/proto/src/imap/mod.rs new file mode 100644 index 000000000..d469bffcc --- /dev/null +++ b/crates/proto/src/imap/mod.rs @@ -0,0 +1,1405 @@ +// SPDX-FileCopyrightText: MailCraft contributors +// SPDX-License-Identifier: MIT OR Apache-2.0 +//! An IMAP4rev1 client (RFC 3501) with the commands a two-way synchronisation needs: reading +//! mailboxes, and changing flags, moving, copying, removing and filing messages (UID MOVE of +//! RFC 6851; UID EXPUNGE and the `COPYUID` answer of RFC 4315). Special-use mailbox flags +//! (RFC 6154) come through in [`Mailbox::flags`] as the server wrote them. Password sign-in prefers +//! advertised SASL PLAIN, with LOGIN as a fallback when PLAIN is not offered; OAuth uses XOAUTH2. +//! +//! There is no plain EXPUNGE and no CLOSE here, on purpose: both remove every message marked +//! `\Deleted` in the mailbox, also those another program marked. + +mod idle; +#[cfg(test)] +mod idle_tests; +mod parse; +mod password; +#[cfg(test)] +mod password_tests; +mod status; +#[cfg(test)] +mod status_tests; +mod utf7; + +pub use idle::IdleEvent; +pub use status::{FolderStatus, MAX_STATUS_BATCH}; + +use std::collections::{BTreeMap, BTreeSet, HashSet}; +use std::io::{Read, Write}; + +use parse::{Piece, Status, StatusLine, Value}; +pub use utf7::{decode_utf7, encode_utf7}; + +use crate::i18n::{Arg, Text}; +use crate::line::Wire; +use crate::said; +use crate::{MAX_LINE, MAX_LITERAL, ProtoError, Secrets, for_trace, tidy, xoauth2}; + +/// Most responses the server may send to one command. +const MAX_RESPONSES: usize = 250_000; +/// Most text (everything outside literals) the server may send in answer to one command. +const MAX_COMMAND_TEXT: usize = 32 << 20; +/// Most mailboxes one LIST keeps; the ones after are read and dropped. More than a run reads +/// (10,000, #991), since some of those listed are never read (views, folders that can't be +/// opened). What is kept is bounded in bytes too ([`MAX_LIST_BYTES`]). +const MAX_MAILBOXES: usize = 12_000; +/// Most bytes of names and flags one LIST keeps, literals included (which +/// [`MAX_COMMAND_TEXT`] doesn't count): 12,000 mailboxes as most servers list them take a +/// megabyte or two; past this the ones after are read and dropped. +const MAX_LIST_BYTES: usize = 16 << 20; +/// Longest mailbox name kept (as the server wrote it); a mailbox with a longer one is left out, +/// since a name cut short would name another mailbox or none. +const MAX_MAILBOX_NAME: usize = 1_024; +/// Longest flag kept, in bytes. +const MAX_FLAG_LEN: usize = 256; +/// Most distinct messages a FETCH may report, beyond twice the mailbox's `EXISTS`. +const FETCH_SLACK: usize = 1_000; +/// Most literals one response may carry. +const MAX_LITERALS: usize = 32; +/// Most text one response may carry outside its literals. +const MAX_TEXT: usize = 4 * MAX_LINE; +/// Most flags kept for one message or mailbox, and most sent in one command. +const MAX_FLAGS: usize = 64; +/// Most of Gmail's labels kept for one message (`X-GM-LABELS`, #1153); the rest are dropped. +pub const MAX_GMAIL_LABELS: usize = 64; +/// Longest of Gmail's labels kept, in bytes as the server wrote it (cut at a character boundary). +const MAX_GMAIL_LABEL_LEN: usize = 256; +/// Most bytes of Gmail's labels one fetch keeps, all its messages together, each label counted +/// with [`LABEL_OVERHEAD`]: past it, a message's labels are not taken (`None`), as if the server +/// hadn't said them. +const MAX_GMAIL_LABEL_BYTES: usize = 32 << 20; +/// What a label kept costs beyond its bytes (its `String`), counted against +/// [`MAX_GMAIL_LABEL_BYTES`] so that many empty or tiny labels can't get past it. +const LABEL_OVERHEAD: usize = std::mem::size_of::(); +/// Text a listing of flags may take for each message the mailbox may report, beyond +/// [`MAX_COMMAND_TEXT`]: a big folder's listing (Gmail's, with labels, runs to a few hundred +/// bytes a message) is never cut short for being big (#1153), and what a hostile server can send +/// stays bounded by the mailbox's size, and by [`MAX_FETCH_TEXT`] whatever size it claims. Only +/// a count: what is kept is bounded on its own ([`MAX_FLAG_BYTES`], [`MAX_GMAIL_LABEL_BYTES`]). +const FETCH_TEXT_PER_MESSAGE: usize = 2 << 10; +/// Most text a listing of flags may take, however many messages the mailbox claims. +const MAX_FETCH_TEXT: usize = 256 << 20; +/// Most bytes of flags one fetch keeps, all its messages together, each message counted with +/// [`ENTRY_OVERHEAD`] and each flag with [`FLAG_OVERHEAD`]: past it the listing fails, so that a +/// server claiming a huge mailbox can't fill memory and no message is taken to have lost its flags. +/// Room for over a million messages with a few flags each. +const MAX_FLAG_BYTES: usize = 256 << 20; +/// What a flag kept costs beyond its bytes (its `String`). +const FLAG_OVERHEAD: usize = std::mem::size_of::(); +/// What a message kept in a listing costs beyond its flags and labels: its entry in the map, with +/// room for the map's own nodes. +const ENTRY_OVERHEAD: usize = 2 * std::mem::size_of::<(u32, (Vec, Option, Option>))>(); +const MAX_CAPABILITIES: usize = 256; +/// Longest string sent in quotes; a longer one goes as a literal. +const MAX_QUOTED: usize = 1_000; +/// Most messages named in one set by [`uid_sets`], and most a `COPYUID` answer may speak of. +const MAX_SET_UIDS: usize = 500; +/// Longest set [`uid_sets`] writes, in characters. +const MAX_SET_TEXT: usize = 800; +/// The most UIDs a search answers with that are taken in. +const MAX_FOUND: usize = 1_000; +/// The most UIDs one of Gmail's searches ([`Imap::uid_search_gmail`]) answers with that are taken +/// in: as many as fit the longest line read, at the longest a UID is written. +pub const MAX_GMAIL_FOUND: usize = 5_000; + +/// An IMAP session on a stream. +pub struct Imap { + wire: Wire, + /// The number in the next command's tag. + next_tag: u32, + secrets: Secrets, + /// What the server said it can do, upper-cased; `None` until it has. + capabilities: Option>, + authenticated: bool, + /// What the mailbox being opened has said about itself so far. + selected: Selected, + /// Every `COPYUID` answer since the last copy or move was sent (`None` for one that couldn't + /// be read); two are as many as it takes to know there was more than one. + copied: Vec>, + /// Every `APPENDUID` answer since the last APPEND was sent, as [`Imap::copied`] is kept. + appended: Vec>, + /// LOGOUT was sent, so BYE is the answer we asked for. + leaving: bool, + /// Bytes of text (outside literals) read since the current command was sent. + text_seen: usize, + /// Most responses the current command may bring. + response_cap: usize, + /// Most text (outside literals) the current command may bring: [`MAX_COMMAND_TEXT`], or more + /// for a listing of a big mailbox's flags. + text_cap: usize, + /// Untagged lines too long to take are read past instead of ending the session, for the + /// current command alone (a Gmail search, #911); `skipped` says one was. + skip_long: bool, + skipped: bool, + /// The tag of the IDLE command the server is waiting in, if it is ([`Imap::idle_begin`]). + idle_tag: Option, + idle_pending: std::collections::VecDeque, +} + +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct Mailbox { + /// Decoded from modified UTF-7. + pub name: String, + /// The name exactly as the server wrote it (use this in commands). + pub raw: String, + pub delimiter: Option, + /// Flags as written, e.g. `\\Noselect`, `\\Sent`, `\\HasChildren`. + pub flags: Vec, +} + +/// The personal IMAP namespace (RFC 2342): `prefix` (as the server spells it, e.g. `"INBOX."`) and +/// hierarchy `delimiter` (`'.'`, `'/'`), if any. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct Namespace { + pub prefix: String, + pub delimiter: Option, +} + +impl Mailbox { + /// Whether the mailbox has `flag` (`\Noselect`), whatever the letter case. + pub fn has_flag(&self, flag: &str) -> bool { + self.flags.iter().any(|f| f.eq_ignore_ascii_case(flag)) + } +} + +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct Selected { + pub exists: u32, + pub uid_validity: u32, + pub uid_next: u32, +} + +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct Fetched { + pub uid: u32, + pub flags: Vec, + /// INTERNALDATE as written by the server, when asked for. + pub internal_date: Option, + /// The whole message (BODY[]), when asked for. + pub body: Option>, + /// Gmail's own id of the message (`X-GM-MSGID`, Google's "Gmail IMAP extensions"), when + /// asked for and given; `None` from every other server. + pub gmail_id: Option, + /// Gmail's labels of the message (`X-GM-LABELS`, Google's "Gmail IMAP extensions", #1153), + /// when asked for and given: as the server wrote them, modified UTF-7 decoded, Gmail's own + /// (`\Inbox`, `\Important`…) with their backslash; at most [`MAX_GMAIL_LABELS`], each cut + /// short. Text from the server, not yet cleaned for showing. `None` from every other server. + pub gmail_labels: Option>, +} + +/// What became of the messages a UID COPY or UID MOVE named, when the server says (the `COPYUID` +/// response code of RFC 4315). +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct Copied { + /// `UIDVALIDITY` of the mailbox the messages went to. + pub uid_validity: u32, + /// Each message's UID where it was, and its UID where it is now. + pub uids: Vec<(u32, u32)>, +} + +/// Where a message given with APPEND went, when the server says (the `APPENDUID` response code +/// of RFC 4315). +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub struct Appended { + /// `UIDVALIDITY` of the mailbox it went to. + pub uid_validity: u32, + /// Its UID there. + pub uid: u32, +} + +/// Neither the stream nor anything secret is shown. +impl std::fmt::Debug for Imap { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Imap").field("next_tag", &self.next_tag).field("authenticated", &self.authenticated).finish_non_exhaustive() + } +} + +/// One response from the server. +enum Response { + /// `+ …`: the server is ready for the rest of the command. + GoAhead, + Status { + tag: Option, + line: StatusLine, + }, + /// Untagged data: `* 3 EXISTS`, `* LIST …`, `* 3 FETCH (…)`. + Data(Vec), +} + +enum Part<'a> { + Text(Vec), + Literal(&'a [u8]), +} + +/// A command being put together (without its tag). +struct Command<'a> { + parts: Vec>, + /// What the log shows in place of the command. + shown: Option<&'static str>, + /// An argument has a NUL, which no IMAP string can carry. + unsendable: bool, +} + +impl<'a> Command<'a> { + fn new(verb: &str) -> Self { + Command { parts: vec![Part::Text(verb.as_bytes().to_vec())], shown: None, unsendable: false } + } + + fn text(&mut self, bytes: &[u8]) { + match self.parts.last_mut() { + Some(Part::Text(text)) => text.extend_from_slice(bytes), + _ => self.parts.push(Part::Text(bytes.to_vec())), + } + } + + /// A bare argument: our own words, or text that was checked. + fn arg(mut self, word: &str) -> Self { + self.text(b" "); + self.text(word.as_bytes()); + self + } + + /// An argument as a quoted string, or as a literal when quotes can't carry it. + fn string(mut self, bytes: &'a [u8]) -> Self { + self.text(b" "); + if bytes.len() <= MAX_QUOTED && bytes.iter().all(|b| matches!(b, b' '..=b'~')) { + let mut quoted = Vec::with_capacity(bytes.len() + 2); + quoted.push(b'"'); + for b in bytes { + if matches!(b, b'"' | b'\\') { + quoted.push(b'\\'); + } + quoted.push(*b); + } + quoted.push(b'"'); + self.text("ed); + } else { + self.unsendable |= bytes.contains(&0); + self.parts.push(Part::Literal(bytes)); + } + self + } + + /// An argument that always goes as a literal (a message). + fn literal(mut self, bytes: &'a [u8]) -> Self { + self.text(b" "); + self.parts.push(Part::Literal(bytes)); + self + } + + fn shown_as(mut self, shown: &'static str) -> Self { + self.shown = Some(shown); + self + } + + /// The command for the log: literals by size only. + fn for_log(&self) -> String { + if let Some(shown) = self.shown { + return shown.to_string(); + } + self.parts + .iter() + .map(|part| match part { + Part::Text(text) => String::from_utf8_lossy(text).into_owned(), + Part::Literal(bytes) => format!("({} bytes)", bytes.len()), + }) + .collect() + } +} + +/// What one FETCH response says about a message. +#[derive(Default)] +struct Item { + uid: u32, + flags: Option>, + internal_date: Option, + body: Option>, + /// The header alone (`BODY[HEADER]`). + header: Option>, + size: Option, + /// Gmail's id of the message (`X-GM-MSGID`). + gmail_id: Option, + /// Gmail's labels of the message (`X-GM-LABELS`). + gmail_labels: Option>, +} + +impl Item { + /// From `n FETCH (name value name value …)`, the names in any order. + fn from(values: Vec) -> Option { + let mut values = values.into_iter(); + values.next()?.number()?; + if !values.next()?.atom()?.eq_ignore_ascii_case("FETCH") { + return None; + } + let Value::List(pairs) = values.next()? else { return None }; + let mut item = Item::default(); + let mut pairs = pairs.into_iter(); + while let Some(name) = pairs.next() { + // Something that isn't a name is skipped, in the hope that a name follows. + let Some(name) = name.atom().map(str::to_ascii_uppercase) else { continue }; + let Some(value) = pairs.next() else { break }; + match (name.as_str(), value) { + ("UID", value) => item.uid = value.number().unwrap_or(0), + ("FLAGS", Value::List(flags)) => item.flags = Some(short_flags(flags)), + ("INTERNALDATE", Value::Str(date)) => item.internal_date = Some(String::from_utf8_lossy(&date).into_owned()), + ("RFC822.SIZE", value) => item.size = value.atom().and_then(|n| n.parse().ok()), + ("X-GM-MSGID", value) => item.gmail_id = value.atom().and_then(gmail_id), + ("X-GM-LABELS", Value::List(labels)) => item.gmail_labels = Some(gmail_labels(labels)), + ("BODY[]" | "RFC822", Value::Str(body)) => item.body = Some(body), + ("BODY[HEADER]" | "RFC822.HEADER", Value::Str(header)) => item.header = Some(header), + _ => {} + } + } + Some(item) + } +} + +/// From `LIST (flags) "delimiter" name`. +fn mailbox_from(values: Vec) -> Option { + let mut values = values.into_iter(); + if !values.next()?.atom()?.eq_ignore_ascii_case("LIST") { + return None; + } + let Value::List(flags) = values.next()? else { return None }; + let delimiter = match values.next()? { + Value::Str(d) => String::from_utf8_lossy(&d).chars().next(), + _ => None, + }; + let raw = values.next()?.into_text()?; + if raw.len() > MAX_MAILBOX_NAME { + return None; + } + Some(Mailbox { name: decode_utf7(&raw), raw, delimiter, flags: short_flags(flags) }) +} + +/// From `NAMESPACE ((prefix delimiter) ...) other shared` (RFC 2342): the first personal namespace. +fn namespace_from(values: Vec) -> Option { + let mut values = values.into_iter(); + if !values.next()?.atom()?.eq_ignore_ascii_case("NAMESPACE") { + return None; + } + let Value::List(personal) = values.next()? else { return None }; + let Value::List(desc) = personal.into_iter().next()? else { return None }; + let mut desc = desc.into_iter(); + let prefix = desc.next()?.into_text()?; + if prefix.len() > MAX_MAILBOX_NAME { + return None; + } + let delimiter = match desc.next()? { + Value::Str(d) => String::from_utf8_lossy(&d).chars().next(), + _ => None, + }; + Some(Namespace { prefix, delimiter }) +} + +/// The flags of a list, as many as are kept and each cut at a character boundary. +fn short_flags(flags: Vec) -> Vec { + flags + .into_iter() + .filter_map(Value::into_text) + .take(MAX_FLAGS) + .map(|mut flag| { + if flag.len() > MAX_FLAG_LEN { + let mut end = MAX_FLAG_LEN; + while !flag.is_char_boundary(end) { + end = end.saturating_sub(1); + } + flag = flag.get(..end).unwrap_or_default().to_owned(); + } + flag + }) + .collect() +} + +/// Gmail's labels of a message (`X-GM-LABELS`): a list of atoms and strings, modified UTF-7 as +/// mailbox names are; as many as are kept, each cut at a character boundary before it is decoded. +/// Anything in the list that isn't an atom or a string (a list) is skipped. +fn gmail_labels(labels: Vec) -> Vec { + labels + .into_iter() + // `NIL` in the list is nothing, not a label (a label called so comes quoted). + .filter(|value| !value.atom().is_some_and(|atom| atom.eq_ignore_ascii_case("NIL"))) + .filter_map(Value::into_text) + .take(MAX_GMAIL_LABELS) + .map(|mut label| { + if label.len() > MAX_GMAIL_LABEL_LEN { + let mut end = MAX_GMAIL_LABEL_LEN; + while !label.is_char_boundary(end) { + end = end.saturating_sub(1); + } + label.truncate(end); + } + decode_utf7(&label) + }) + .collect() +} + +/// A message set as ranges of UIDs (`*` as `top`); `None` when it can't be read. +fn set_ranges(set: &str, top: u32) -> Option> { + let bound = |text: &str| if text == "*" { Some(top) } else { number(text) }; + set.split(',') + .map(|part| { + // A wildcard-only fetch is resolved by the server, not a stale client snapshot. + if part == "*" || part == "*:*" { + return Some((1, top)); + } + let (a, b) = match part.split_once(':') { + Some((a, b)) => (bound(a)?, bound(b)?), + None => (bound(part)?, bound(part)?), + }; + Some((a.min(b), a.max(b))) + }) + .collect() +} + +/// What a FETCH of a set may report: only UIDs in the set, and not more distinct +/// ones than a mailbox of this size can hold. +struct Wanted { + ranges: Vec<(u32, u32)>, + cap: usize, + over: bool, +} + +impl Wanted { + fn new(set: &str, selected: &Selected) -> Option { + // UIDNEXT is a SELECT-time snapshot; new deliveries can have larger UIDs. + let ranges = set_ranges(set, u32::MAX)?; + let cap = usize::try_from(selected.exists).unwrap_or(usize::MAX).saturating_mul(2).saturating_add(FETCH_SLACK); + Some(Wanted { ranges, cap, over: false }) + } + + /// Most responses a fetch of this mailbox may bring: one for each message it may report, but + /// never fewer than any other command. + fn responses(&self) -> usize { + self.cap.max(MAX_RESPONSES) + } + + fn wants(&self, uid: u32) -> bool { + uid != 0 && self.ranges.iter().any(|(from, to)| (*from..=*to).contains(&uid)) + } + + /// Whether one more distinct UID fits after `count`; if not, the command fails. + fn room(&mut self, count: usize) -> bool { + if count >= self.cap { + self.over = true; + } + !self.over + } + + fn check(&self) -> Result<(), ProtoError> { + if self.over { Err(ProtoError::Protocol(said!("the server reported more messages than the mailbox holds"))) } else { Ok(()) } + } +} + +/// A message set: `1:*`, `5,9,12:20`. +fn is_set(set: &str) -> bool { + !set.is_empty() && set.len() <= MAX_QUOTED && set.bytes().all(|b| b.is_ascii_digit() || matches!(b, b':' | b',' | b'*')) +} + +/// A flag or keyword: `\Seen`, `$Forwarded`. +fn is_flag(flag: &str) -> bool { + let word = flag.strip_prefix('\\').unwrap_or(flag); + !word.is_empty() + && word.len() <= 100 + && word.bytes().all(|b| b.is_ascii_graphic() && !matches!(b, b'(' | b')' | b'{' | b'%' | b'*' | b'"' | b'\\' | b']')) +} + +/// `(\Seen \Flagged)`, once every flag is known to be one. +fn flag_list(flags: &[&str]) -> Result { + if flags.len() > MAX_FLAGS { + return Err(ProtoError::Protocol(said!("too many flags for one command"))); + } + match flags.iter().find(|f| !is_flag(f)) { + Some(bad) => Err(ProtoError::Protocol(said!("\"{flag}\" can't be used as a flag", flag = tidy(bad)))), + None => Ok(format!("({})", flags.join(" "))), + } +} + +/// Gmail's id of a message (`X-GM-MSGID`): a 64-bit number, written in digits alone; 0 is none. +fn gmail_id(text: &str) -> Option { + if text.is_empty() || !text.bytes().all(|b| b.is_ascii_digit()) { + return None; + } + text.parse().ok().filter(|id| *id != 0) +} + +/// A number as IMAP writes one: digits and nothing else. +fn number(text: &str) -> Option { + if text.is_empty() || !text.bytes().all(|b| b.is_ascii_digit()) { + return None; + } + text.parse().ok() +} + +/// The UIDs a set names, in the order written (`4,7:9` is 4, 7, 8, 9). `None` for a set that +/// doesn't name its messages one by one beyond doubt: `*`, zero, a range written backwards, or +/// more than [`MAX_SET_UIDS`] numbers. +fn uids_of(set: &str) -> Option> { + let mut out: Vec = Vec::new(); + for part in set.split(',') { + let (first, last) = match part.split_once(':') { + Some((first, last)) => (number(first)?, number(last)?), + None => { + let one = number(part)?; + (one, one) + } + }; + if first == 0 || first > last || (last - first) as usize >= MAX_SET_UIDS.saturating_sub(out.len()) { + return None; + } + out.extend(first..=last); + } + Some(out) +} + +/// A set for a command that changes things: it names its messages number by number. `1:*` +/// would take in messages nobody looked at. +fn named(set: &str) -> Result<&str, ProtoError> { + if set.len() <= MAX_QUOTED && uids_of(set).is_some() { + Ok(set) + } else { + Err(ProtoError::Protocol(said!("\"{set}\" doesn't name the messages to change", set = tidy(set)))) + } +} + +/// From the text of a `COPYUID` code: ` `. +/// `None` unless it pairs every message beyond doubt (the first set strictly ascending, the +/// second as long and without repeats): a wrong pairing would tie a message here to another one +/// on the server. +fn copied_from(arg: &str) -> Option { + let mut words = arg.split_whitespace(); + let uid_validity = number(words.next()?).filter(|validity| *validity != 0)?; + let (from, to) = (uids_of(words.next()?)?, uids_of(words.next()?)?); + let mut distinct = to.clone(); + distinct.sort_unstable(); + distinct.dedup(); + if words.next().is_some() || from.len() != to.len() || distinct.len() != to.len() || !from.is_sorted_by(|a, b| a < b) { + return None; + } + Some(Copied { uid_validity, uids: from.into_iter().zip(to).collect() }) +} + +/// From the text of an `APPENDUID` code: ` `, for one message. `None` for +/// anything else (a set of UIDs speaks of more than the one message given). +fn appended_from(arg: &str) -> Option { + let mut words = arg.split_whitespace(); + let uid_validity = number(words.next()?).filter(|validity| *validity != 0)?; + let uid = number(words.next()?).filter(|uid| *uid != 0)?; + words.next().is_none().then_some(Appended { uid_validity, uid }) +} + +/// Whether `text` is an IMAP `date-time` without its quotes (RFC 3501): `01-Jul-2003 09:52:37 +/// +0000`, the day padded with a space or a nought. +fn is_date_time(text: &str) -> bool { + let b = text.as_bytes(); + let digits = |range: std::ops::Range| b.get(range).is_some_and(|d| d.iter().all(u8::is_ascii_digit)); + let at = |i: usize, c: u8| b.get(i) == Some(&c); + b.len() == 26 + && (digits(0..2) || (at(0, b' ') && digits(1..2))) + && at(2, b'-') + && b.get(3..6).is_some_and(|m| m.iter().all(u8::is_ascii_alphabetic)) + && at(6, b'-') + && digits(7..11) + && at(11, b' ') + && digits(12..14) + && at(14, b':') + && digits(15..17) + && at(17, b':') + && digits(18..20) + && at(20, b' ') + && (at(21, b'+') || at(21, b'-')) + && digits(22..26) +} + +/// Whether [`Imap::uid_search_header`] can look for `text`: printable ASCII, at most +/// [`MAX_QUOTED`] bytes. What it can't be asked for, it refuses unsent. +pub fn searchable(text: &str) -> bool { + !text.is_empty() && text.len() <= MAX_QUOTED && text.bytes().all(|b| matches!(b, b' '..=b'~')) +} + +/// UIDs as message sets for commands (`4,7:9,12`), each with the UIDs it names: sorted, each UID +/// once, consecutive numbers as ranges, and no set longer than one command should carry. A +/// range only ever spans numbers that were asked for. +pub fn uid_sets(uids: &[u32]) -> Vec<(String, Vec)> { + let mut sorted: Vec = uids.iter().copied().filter(|uid| *uid != 0).collect(); + sorted.sort_unstable(); + sorted.dedup(); + let mut sets = Vec::new(); + let (mut text, mut uids_named) = (String::new(), Vec::new()); + let mut at = 0; + // Every round takes at least one UID off the list. + while let Some(&first) = sorted.get(at) { + let (mut last, mut next) = (first, at + 1); + while uids_named.len() + (next - at) < MAX_SET_UIDS && sorted.get(next).is_some_and(|uid| last.checked_add(1) == Some(*uid)) { + last = last.saturating_add(1); + next += 1; + } + let range = if last == first { first.to_string() } else { format!("{first}:{last}") }; + if !text.is_empty() && text.len() + 1 + range.len() > MAX_SET_TEXT { + sets.push((std::mem::take(&mut text), std::mem::take(&mut uids_named))); + } + if !text.is_empty() { + text.push(','); + } + text.push_str(&range); + uids_named.extend_from_slice(sorted.get(at..next).unwrap_or(&[])); + at = next; + if uids_named.len() >= MAX_SET_UIDS { + sets.push((std::mem::take(&mut text), std::mem::take(&mut uids_named))); + } + } + if !text.is_empty() { + sets.push((text, uids_named)); + } + sets +} + +fn ignore(_: Vec) {} + +impl Imap { + /// Read the greeting (`* OK` or `* PREAUTH`; `* BYE` is an error). + pub fn connect(stream: S) -> Result { + let mut imap = Self::resume(stream); + match imap.read_response()? { + Response::Status { tag: None, line } => match line.status { + Status::Ok | Status::Preauth => { + imap.authenticated = line.status == Status::Preauth; + imap.note_status(&line); + Ok(imap) + } + Status::Bye => Err(ProtoError::Rejected(imap.refusal(&line))), + Status::No | Status::Bad => { + Err(ProtoError::Protocol(said!("the server greeted with a refusal: {reason}", reason = Arg::said(imap.refusal(&line))))) + } + }, + _ => Err(ProtoError::Protocol(said!("the server didn't greet like an IMAP server"))), + } + } + + /// Continue on a stream that already greeted (after the caller wrapped it in TLS). + pub fn resume(stream: S) -> Self { + Imap { + wire: Wire::new(stream), + next_tag: 1, + secrets: Secrets::default(), + capabilities: None, + authenticated: false, + selected: Selected::default(), + copied: Vec::new(), + appended: Vec::new(), + leaving: false, + text_seen: 0, + response_cap: MAX_RESPONSES, + text_cap: MAX_COMMAND_TEXT, + skip_long: false, + skipped: false, + idle_tag: None, + idle_pending: std::collections::VecDeque::new(), + } + } + + /// Whether the session is signed in: after [`login`](Self::login) or + /// [`authenticate_xoauth2`](Self::authenticate_xoauth2), or from the start when the server greeted with PREAUTH. + pub fn is_authenticated(&self) -> bool { + self.authenticated + } + + /// 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() + } + + /// Whether the server has said it can do `capability` (upper-cased); `false` while it hasn't said anything. + fn offers(&self, capability: &str) -> bool { + self.capabilities.as_ref().is_some_and(|caps| caps.iter().any(|c| c == capability)) + } + + /// Upper-cased capability atoms (`IMAP4REV1`, `STARTTLS`, `SPECIAL-USE`…). + pub fn capabilities(&mut self) -> Result, ProtoError> { + self.capabilities = None; + self.run(Command::new("CAPABILITY"), &mut ignore)?; + Ok(self.capabilities.clone().unwrap_or_default()) + } + + /// Send STARTTLS and hand the stream back for the caller to wrap; call `resume` afterwards. + pub fn starttls(mut self) -> Result { + self.run(Command::new("STARTTLS"), &mut ignore)?; + // Anything after the go-ahead was slipped in before encryption started. + if self.wire.has_pending() { + return Err(ProtoError::Protocol(said!("the server sent data before the secure connection started"))); + } + Ok(self.wire.into_inner()) + } + + /// LOGIN with properly quoted (or literal) strings. NO → `ProtoError::Auth`. + pub fn login(&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"))); + } + // RFC 3501 §6.2.3: a server that says LOGINDISABLED must not be sent a password. + if self.offers("LOGINDISABLED") { + return Err(ProtoError::Auth(said!("the server doesn't take a password on this connection"))); + } + self.secrets.add(password); + let command = Command::new("LOGIN").string(user.as_bytes()).string(password.as_bytes()).shown_as("LOGIN ***"); + let line = self.exchange(command, &mut ignore)?; + match line.status { + Status::Ok => { + self.authenticated = true; + Ok(()) + } + Status::No => Err(ProtoError::Auth(self.refusal(&line))), + _ => Err(ProtoError::Rejected(self.refusal(&line))), + } + } + + /// AUTHENTICATE XOAUTH2: an OAuth access token in place of a password. NO → `ProtoError::Auth`. + /// + /// The token goes out with the command (RFC 4959) only to a server that listed both + /// `SASL-IR` and `AUTH=XOAUTH2`. Any other server, one that listed neither or hasn't said + /// what it can do, is tried all the same, but asked first: it gets the token after its + /// go-ahead, so one that doesn't know the mechanism refuses without having seen it. + pub fn authenticate_xoauth2(&mut self, user: &str, token: &str) -> Result<(), ProtoError> { + let payload = xoauth2(user, token)?; + self.secrets.add(token); + self.secrets.add(&payload); + let inline = self.offers("SASL-IR") && self.offers("AUTH=XOAUTH2"); + let tag = self.tag(); + log::trace!("C: {tag} AUTHENTICATE XOAUTH2{}", if inline { " ***" } else { "" }); + let mut out = format!("{tag} AUTHENTICATE XOAUTH2"); + if inline { + out.push(' '); + out.push_str(&payload); + } + out.push_str("\r\n"); + self.wire.write(out.as_bytes())?; + self.wire.flush()?; + // What each `+` from the server is answered with: the token (unless it went with the + // command), an empty line for the reasons a refusal starts with (JSON in base64), and + // for a question after that, the end of the exchange. + let answers = [(payload.as_str(), "***"), ("", ""), ("*", "*")]; + let mut asked = usize::from(inline); + let line = loop { + if let Some(line) = self.read_until(&tag, true, &mut ignore)? { + break line; + } + let Some((answer, shown)) = answers.get(asked) else { + return Err(ProtoError::Protocol(said!("the server asked for more than a sign-in has"))); + }; + asked += 1; + log::trace!("C: {shown}"); + self.wire.write(format!("{answer}\r\n").as_bytes())?; + self.wire.flush()?; + }; + match line.status { + // The exchange was called off, whatever the server makes of that. + _ if asked == answers.len() => Err(ProtoError::Auth(said!("the server asked for more than a user name and access token"))), + // Nobody is signed in by a token that was never sent. + Status::Ok if asked == 0 => Err(ProtoError::Protocol(said!("the server ended the command early"))), + Status::Ok => { + self.authenticated = true; + Ok(()) + } + Status::No => Err(ProtoError::Auth(self.refusal(&line))), + _ => Err(ProtoError::Rejected(self.refusal(&line))), + } + } + + /// LIST "" "*". + pub fn list(&mut self) -> Result, ProtoError> { + self.list_counted().map(|(list, _)| list) + } + + /// [`list`](Self::list), and how many more mailboxes the server listed that were read and + /// dropped because the list was full ([`MAX_MAILBOXES`], [`MAX_LIST_BYTES`]): 0 when it + /// was kept whole. + pub fn list_counted(&mut self) -> Result<(Vec, usize), ProtoError> { + let mut out: Vec = Vec::new(); + let mut seen = HashSet::new(); + let (mut kept, mut dropped) = (0usize, 0usize); + self.run(Command::new("LIST").arg("\"\"").arg("\"*\""), &mut |values| { + let full = out.len() >= MAX_MAILBOXES || kept >= MAX_LIST_BYTES; + // A mailbox the server names twice is listed once; past either cap, nothing is kept. + let Some(mailbox) = mailbox_from(values) else { return }; + if full { + dropped = dropped.saturating_add(1); + } else if seen.insert(mailbox.raw.clone()) { + // The name twice (as written, decoded) and once more in `seen`, and the flags. + let size = mailbox.raw.len().saturating_mul(2).saturating_add(mailbox.name.len()); + kept = mailbox.flags.iter().fold(kept.saturating_add(size), |kept, flag| kept.saturating_add(flag.len())); + out.push(mailbox); + } + })?; + Ok((out, dropped)) + } + + /// NAMESPACE (RFC 2342): the server's first personal namespace, or `None` when the server + /// offers no `NAMESPACE` capability or names no personal namespace. + pub fn namespace(&mut self) -> Result, ProtoError> { + if !self.offers("NAMESPACE") { + return Ok(None); + } + let mut found = None; + self.run(Command::new("NAMESPACE"), &mut |values| { + if found.is_none() { + found = namespace_from(values); + } + })?; + Ok(found) + } + + /// EXAMINE (read-only) or SELECT. + pub fn select(&mut self, raw_name: &str, read_only: bool) -> Result { + self.selected = Selected::default(); + let command = Command::new(if read_only { "EXAMINE" } else { "SELECT" }).string(raw_name.as_bytes()); + self.run(command, &mut ignore)?; + Ok(self.selected.clone()) + } + + /// UID FETCH (UID FLAGS): every message in the set with its flags. `set` like "1:*" or "5,9,12:20". + /// + /// The messages come back in UID order, each once. + pub fn uid_fetch_flags(&mut self, set: &str) -> Result, ProtoError> { + self.fetch_flags(set, false, false) + } + + /// [`uid_fetch_flags`](Self::uid_fetch_flags), with Gmail's id and labels of each message as + /// well (`UID FETCH (UID FLAGS X-GM-MSGID X-GM-LABELS)`, in [`Fetched::gmail_id`] and + /// [`Fetched::gmail_labels`]): for Gmail's server alone, which documents them among its IMAP + /// extensions. A message it gives no id, or one that isn't a number, has none; one it gives + /// no labels has `None` there, and one past [`MAX_GMAIL_LABEL_BYTES`] of labels in the fetch + /// too. + pub fn uid_fetch_flags_gmail(&mut self, set: &str) -> Result, ProtoError> { + self.fetch_flags(set, true, true) + } + + /// [`uid_fetch_flags`](Self::uid_fetch_flags), with Gmail's labels of each message as well but + /// not its id (`UID FETCH (UID FLAGS X-GM-LABELS)`, in [`Fetched::gmail_labels`]): for a + /// Gmail folder whose ids aren't wanted (every folder but the Inbox), so that its listing is + /// no longer than it has to be. + pub fn uid_fetch_flags_labels(&mut self, set: &str) -> Result, ProtoError> { + self.fetch_flags(set, false, true) + } + + fn fetch_flags(&mut self, set: &str, ids: bool, labels_wanted: bool) -> Result, ProtoError> { + type FetchedFlags = (Vec, Option, Option>); + let mut found: BTreeMap = BTreeMap::new(); + // The bytes of labels and of flags kept so far, all messages together. + let mut label_bytes = 0usize; + let mut flag_bytes = 0usize; + let items = match (ids, labels_wanted) { + (true, true) => "(UID FLAGS X-GM-MSGID X-GM-LABELS)", + (true, false) => "(UID FLAGS X-GM-MSGID)", + (false, true) => "(UID FLAGS X-GM-LABELS)", + (false, false) => "(UID FLAGS)", + }; + let command = Self::fetch(set, items)?; + let mut wanted = Wanted::new(set, &self.selected).ok_or_else(|| ProtoError::Protocol(said!("not a set of messages")))?; + self.response_cap = wanted.responses(); + let claimed = usize::try_from(self.selected.exists).unwrap_or(usize::MAX); + self.text_cap = claimed.saturating_mul(FETCH_TEXT_PER_MESSAGE).clamp(MAX_COMMAND_TEXT, MAX_FETCH_TEXT); + let answered = self.run(command, &mut |values| { + // A response with a UID shows the message is there, even one that forgot the flags. + if flag_bytes <= MAX_FLAG_BYTES + && let Some(item) = Item::from(values) + && wanted.wants(item.uid) + && (found.contains_key(&item.uid) || wanted.room(found.len())) + { + // Each word counted as it comes, a repeat included: past the budget nothing more + // is kept and the listing fails below. + let size = item.flags.iter().flatten().map(|flag| flag.len().saturating_add(FLAG_OVERHEAD)).sum::(); + let entry = if found.contains_key(&item.uid) { 0 } else { ENTRY_OVERHEAD }; + flag_bytes = flag_bytes.saturating_add(size).saturating_add(entry); + if flag_bytes > MAX_FLAG_BYTES { + return; + } + let (flags, id, labels) = found.entry(item.uid).or_default(); + // When the server speaks of a message twice, its later word counts. + if let Some(later) = item.flags { + *flags = later; + } + if ids && item.gmail_id.is_some() { + *id = item.gmail_id; + } + if labels_wanted && let Some(later) = item.gmail_labels { + let size = later.iter().map(|label| label.len().saturating_add(LABEL_OVERHEAD)).sum::(); + if label_bytes.saturating_add(size) <= MAX_GMAIL_LABEL_BYTES { + label_bytes = label_bytes.saturating_add(size); + *labels = Some(later); + } + } + } + }); + self.response_cap = MAX_RESPONSES; + self.text_cap = MAX_COMMAND_TEXT; + answered?; + if flag_bytes > MAX_FLAG_BYTES { + return Err(ProtoError::Protocol(said!("more flags than one listing keeps"))); + } + wanted.check()?; + Ok(found + .into_iter() + .map(|(uid, (flags, gmail_id, gmail_labels))| Fetched { uid, flags, internal_date: None, body: None, gmail_id, gmail_labels }) + .collect()) + } + + /// UID FETCH (UID RFC822.SIZE): the size in bytes of every message in the set, in UID order. + pub fn uid_fetch_sizes(&mut self, set: &str) -> Result, ProtoError> { + let mut out: Vec<(u32, u64)> = Vec::new(); + let command = Self::fetch(set, "(UID RFC822.SIZE)")?; + let mut wanted = Wanted::new(set, &self.selected).ok_or_else(|| ProtoError::Protocol(said!("not a set of messages")))?; + self.response_cap = wanted.responses(); + let answered = self.run(command, &mut |values| { + if let Some(Item { uid, size: Some(size), .. }) = Item::from(values) + && wanted.wants(uid) + && wanted.room(out.len()) + { + out.push((uid, size)); + } + }); + self.response_cap = MAX_RESPONSES; + answered?; + wanted.check()?; + out.sort_by_key(|(uid, _)| *uid); + out.dedup_by_key(|(uid, _)| *uid); + Ok(out) + } + + /// UID FETCH (UID FLAGS INTERNALDATE BODY.PEEK[]); `None` when the UID is gone. + pub fn uid_fetch_message(&mut self, uid: u32) -> Result, ProtoError> { + self.fetch_one(uid, "(UID FLAGS INTERNALDATE BODY.PEEK[])", false) + } + + /// UID FETCH (UID FLAGS INTERNALDATE BODY.PEEK[HEADER]): the header alone of a message + /// that is not taken whole (one that is too large), in [`Fetched::body`], up to and with the + /// empty line that ends it. `None` when the UID is gone. + pub fn uid_fetch_header(&mut self, uid: u32) -> Result, ProtoError> { + self.fetch_one(uid, "(UID FLAGS INTERNALDATE BODY.PEEK[HEADER])", true) + } + + /// One message with its flags and date, and either all of it or (`header_only`) its header. + fn fetch_one(&mut self, uid: u32, items: &str, header_only: bool) -> Result, ProtoError> { + if uid == 0 { + return Ok(None); + } + let mut found: Option = None; + self.run(Self::fetch(&uid.to_string(), items)?, &mut |values| { + // Other messages may be mentioned in passing; this one may come in more than one response. + if let Some(item) = Item::from(values) + && item.uid == uid + { + let message = found.get_or_insert_with(|| Fetched { uid, ..Default::default() }); + if let Some(flags) = item.flags { + message.flags = flags; + } + message.internal_date = item.internal_date.or(message.internal_date.take()); + // Only what was asked for: a whole message in answer to a question about its + // header is not taken in. + let asked_for = if header_only { item.header } else { item.body }; + message.body = asked_for.or(message.body.take()); + } + })?; + Ok(found.filter(|message| message.body.is_some())) + } + + /// UID STORE +FLAGS.SILENT / -FLAGS.SILENT (flags). + pub fn uid_store(&mut self, uid: u32, add: bool, flags: &[&str]) -> Result<(), ProtoError> { + let flags = flag_list(flags)?; + if uid == 0 { + return Err(ProtoError::Protocol(said!("a message that isn't on the server has no flags there"))); + } + self.store(&uid.to_string(), add, &flags) + } + + /// UID STORE +FLAGS.SILENT / -FLAGS.SILENT (flags): the same change for every message + /// the set names (number by number, as [`uid_sets`] writes it; `1:*` is refused). A UID that + /// is no longer there is passed over by the server without a word. + pub fn uid_store_set(&mut self, set: &str, add: bool, flags: &[&str]) -> Result<(), ProtoError> { + let flags = flag_list(flags)?; + self.store(named(set)?, add, &flags) + } + + /// UID SEARCH UNDELETED HEADER : the messages of the open mailbox, other than + /// those marked as deleted, whose header field `field` has `text` in it (the server matches a + /// part of the field, whatever its case), by UID in UID order, at most [`MAX_FOUND`] of them. + /// `field` is a field's name, and `text` one that [`searchable`] lets through: anything else + /// is refused unsent. + pub fn uid_search_header(&mut self, field: &str, text: &str) -> Result, ProtoError> { + if field.is_empty() || !field.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-') { + return Err(ProtoError::Protocol(said!("\"{field}\" is not the name of a header field", field = tidy(field)))); + } + if !searchable(text) { + return Err(ProtoError::Protocol(said!("the text can't be looked for on the server"))); + } + let mut found = BTreeSet::new(); + let command = Command::new("UID SEARCH UNDELETED HEADER").arg(field).string(text.as_bytes()); + self.run(command, &mut |values| { + if values.first().and_then(Value::atom).is_some_and(|word| word.eq_ignore_ascii_case("SEARCH")) { + let uids = values.iter().skip(1).filter_map(Value::atom).filter_map(|n| n.parse::().ok()).filter(|uid| *uid != 0); + for uid in uids { + if found.len() >= MAX_FOUND { + break; + } + found.insert(uid); + } + } + })?; + Ok(found.into_iter().collect()) + } + + /// UID SEARCH UID UNDELETED X-GM-RAW "": the messages of the open mailbox, among + /// those `set` names and not marked as deleted, that Gmail's own search finds for `query` + /// (`category:social`), by UID in UID order. `X-GM-RAW` is Gmail's (Google's "Gmail IMAP extensions"): for Gmail's server alone. + /// + /// The query goes in quotes, without the CR, LF and NUL that could end the command early; one + /// that is empty then, or isn't printable ASCII within [`MAX_QUOTED`] bytes, is refused unsent. + /// Of the answer, only UIDs inside `set` are taken, at most [`MAX_GMAIL_FOUND`] of them: a + /// caller that wants them all asks for sets of fewer messages than that. An answer longer than + /// [`MAX_LINE`](crate::MAX_LINE) is read past and refused ([`ProtoError::Rejected`]): the + /// session goes on. + pub fn uid_search_gmail(&mut self, set: &str, query: &str) -> Result, ProtoError> { + if !is_set(set) { + return Err(ProtoError::Protocol(said!("\"{set}\" is not a set of messages", set = tidy(set)))); + } + let ranges = set_ranges(set, u32::MAX).ok_or_else(|| ProtoError::Protocol(said!("not a set of messages")))?; + let query: String = query.chars().filter(|c| !matches!(c, '\r' | '\n' | '\0')).collect(); + if !searchable(&query) { + return Err(ProtoError::Protocol(said!("the text can't be looked for on the server"))); + } + let mut found = BTreeSet::new(); + // Messages marked as deleted aren't shown, so they aren't asked about either. + let command = Command::new("UID SEARCH UID").arg(set).arg("UNDELETED X-GM-RAW").string(query.as_bytes()); + (self.skip_long, self.skipped) = (true, false); + let answer = self.run(command, &mut |values| { + if values.first().and_then(Value::atom).is_some_and(|word| word.eq_ignore_ascii_case("SEARCH")) { + let uids = values.iter().skip(1).filter_map(Value::number).filter(|uid| *uid != 0); + for uid in uids.filter(|uid| ranges.iter().any(|(from, to)| (*from..=*to).contains(uid))) { + if found.len() >= MAX_GMAIL_FOUND { + break; + } + found.insert(uid); + } + } + }); + let skipped = std::mem::take(&mut self.skipped); + self.skip_long = false; + answer?; + // An answer too long to read is no answer: the session goes on without it. + if skipped { + return Err(ProtoError::Rejected(said!("the server's answer was longer than {kb} KB", kb = crate::MAX_LINE / 1024))); + } + Ok(found.into_iter().collect()) + } + + fn store(&mut self, set: &str, add: bool, flags: &str) -> Result<(), ProtoError> { + // No flags: nothing to ask of the server. + if flags == "()" { + return Ok(()); + } + let command = Command::new("UID STORE").arg(set).arg(if add { "+FLAGS.SILENT" } else { "-FLAGS.SILENT" }).arg(flags); + self.run(command, &mut ignore).map(|_| ()) + } + + /// UID MOVE (RFC 6851, for a server that offers `MOVE`): the messages leave + /// the open mailbox for the named one in one step. Answers where they are now when the + /// server says so beyond doubt (`COPYUID`), `None` otherwise. + pub fn uid_move(&mut self, set: &str, raw_name: &str) -> Result, ProtoError> { + self.transfer("UID MOVE", set, raw_name) + } + + /// UID COPY : copies of the messages are added to the named mailbox. Answers + /// like [`uid_move`](Self::uid_move). + pub fn uid_copy(&mut self, set: &str, raw_name: &str) -> Result, ProtoError> { + self.transfer("UID COPY", set, raw_name) + } + + fn transfer(&mut self, verb: &str, set: &str, raw_name: &str) -> Result, ProtoError> { + let command = Command::new(verb).arg(named(set)?).string(raw_name.as_bytes()); + self.copied.clear(); + let done = self.run(command, &mut ignore); + // One answer that could be read, or nothing is known: two that might disagree are none. + let copied = match std::mem::take(&mut self.copied).as_mut_slice() { + [only] => only.take(), + _ => None, + }; + done.map(|_| copied) + } + + /// UID EXPUNGE (RFC 4315): the messages of the set that are marked `\Deleted` go for + /// good, and no others. Refused unsent unless the server has said `UIDPLUS`: a server + /// without it only knows the EXPUNGE that takes every marked message of the mailbox. + pub fn uid_expunge(&mut self, set: &str) -> Result<(), ProtoError> { + let set = named(set)?; + if !self.offers("UIDPLUS") { + return Err(ProtoError::Protocol(said!("the server can't remove single messages (it doesn't offer UIDPLUS)"))); + } + self.run(Command::new("UID EXPUNGE").arg(set), &mut ignore).map(|_| ()) + } + + /// CREATE . `raw_name` is the name as the server wants it: in modified UTF-7 + /// ([`encode_utf7`]), its levels joined with the server's own delimiter. + pub fn create(&mut self, raw_name: &str) -> Result<(), ProtoError> { + self.run(Command::new("CREATE").string(raw_name.as_bytes()), &mut ignore).map(|_| ()) + } + + /// SUBSCRIBE : other mail programs list subscribed mailboxes only. + pub fn subscribe(&mut self, raw_name: &str) -> Result<(), ProtoError> { + self.run(Command::new("SUBSCRIBE").string(raw_name.as_bytes()), &mut ignore).map(|_| ()) + } + + /// APPEND with a literal (handles the `+` continuation). + pub fn append(&mut self, raw_name: &str, flags: &[&str], message: &[u8]) -> Result<(), ProtoError> { + self.append_at(raw_name, flags, None, message).map(|_| ()) + } + + /// [`append`](Self::append), with the time the server is to keep as the message's arrival + /// (its `INTERNALDATE`, an IMAP `date-time` such as `01-Jul-2003 09:52:37 +0000`) when one is + /// given. Answers where the message went when the server says so beyond doubt (`APPENDUID`), + /// `None` otherwise. + pub fn append_at(&mut self, raw_name: &str, flags: &[&str], date: Option<&str>, message: &[u8]) -> Result, ProtoError> { + let mut command = Command::new("APPEND").string(raw_name.as_bytes()); + if !flags.is_empty() { + command = command.arg(&flag_list(flags)?); + } + if let Some(date) = date { + if !is_date_time(date) { + return Err(ProtoError::Protocol(said!("\"{date}\" is not a date and time IMAP can carry", date = tidy(date)))); + } + command = command.arg(&format!("\"{date}\"")); + } + self.appended.clear(); + let done = self.run(command.literal(message), &mut ignore); + // One answer that could be read, or nothing is known. + let appended = match std::mem::take(&mut self.appended).as_mut_slice() { + [only] => only.take(), + _ => None, + }; + done.map(|_| appended) + } + + /// LOGOUT. A server that hangs up without answering has logged us out all the same. + pub fn logout(mut self) -> Result<(), ProtoError> { + self.leaving = true; + match self.run(Command::new("LOGOUT"), &mut ignore) { + Ok(_) | Err(ProtoError::Io(_)) => Ok(()), + Err(e) => Err(e), + } + } + + fn fetch(set: &str, items: &str) -> Result, ProtoError> { + if !is_set(set) { + return Err(ProtoError::Protocol(said!("\"{set}\" is not a set of messages", set = tidy(set)))); + } + Ok(Command::new("UID FETCH").arg(set).arg(items)) + } + + /// How many commands have been sent on this connection (the tags used so far). + pub fn commands(&self) -> u32 { + self.next_tag.wrapping_sub(1) + } + + /// The tag of the next command. + fn tag(&mut self) -> String { + let tag = format!("A{:04}", self.next_tag); + self.next_tag = self.next_tag.wrapping_add(1); + tag + } + + /// Run a command that must end in OK; untagged data goes to `on_data` as it arrives. + fn run(&mut self, command: Command<'_>, on_data: &mut dyn FnMut(Vec)) -> Result { + let line = self.exchange(command, on_data)?; + match line.status { + Status::Ok => Ok(line), + _ => Err(ProtoError::Rejected(self.refusal(&line))), + } + } + + /// Send a command and read up to its tagged answer: OK, NO or BAD. + fn exchange(&mut self, command: Command<'_>, on_data: &mut dyn FnMut(Vec)) -> Result { + if command.unsendable { + return Err(ProtoError::Protocol(said!("the text has a character that can't be sent"))); + } + let tag = self.tag(); + self.text_seen = 0; + if log::log_enabled!(log::Level::Trace) { + log::trace!("C: {tag} {}", for_trace(&self.secrets.hide(&command.for_log()))); + } + let mut out = Vec::with_capacity(128); + out.extend_from_slice(tag.as_bytes()); + out.push(b' '); + for part in &command.parts { + match part { + Part::Text(text) => out.extend_from_slice(text), + Part::Literal(bytes) => { + // A literal is announced, and only sent once the server says `+`. + out.extend_from_slice(format!("{{{}}}\r\n", bytes.len()).as_bytes()); + self.wire.write(&out)?; + self.wire.flush()?; + out.clear(); + match self.read_until(&tag, true, on_data)? { + None => {} + // The command can't have succeeded without the rest of it. + Some(line) if line.status == Status::Ok => return Err(ProtoError::Protocol(said!("the server ended the command early"))), + Some(refused) => return Ok(refused), + } + self.wire.write(bytes)?; + } + } + } + out.extend_from_slice(b"\r\n"); + self.wire.write(&out)?; + self.wire.flush()?; + match self.read_until(&tag, false, on_data)? { + Some(line) => Ok(line), + None => Err(ProtoError::Protocol(said!("the server asked for more than the command had"))), + } + } + + /// Read responses up to the command's tagged answer (`Some`) or, when a literal is waiting to + /// be sent, the server's go-ahead (`None`). + fn read_until(&mut self, tag: &str, literal_waiting: bool, on_data: &mut dyn FnMut(Vec)) -> Result, ProtoError> { + for _ in 0..self.response_cap { + let response = self.read_response()?; + if self.text_seen > self.text_cap { + return Err(ProtoError::Protocol(said!("the server sent too much in answer to one command"))); + } + match response { + Response::GoAhead if literal_waiting => return Ok(None), + Response::GoAhead => return Err(ProtoError::Protocol(said!("the server asked for more than the command had"))), + Response::Status { tag: Some(answered), line } => { + if answered != 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); + return Ok(Some(line)); + } + Response::Status { tag: None, line } => { + if line.status == Status::Bye && !self.leaving { + return Err(ProtoError::Io(said!("the server ended the session: {reason}", reason = Arg::said(self.refusal(&line))))); + } + self.note_status(&line); + } + Response::Data(values) => { + self.note_data(&values); + on_data(values); + } + } + } + Err(ProtoError::Protocol(said!("the server sent too many responses to one command"))) + } + + /// A line of the server's text, counted against what one command may take. + fn read_text(&mut self) -> Result, ProtoError> { + loop { + let line = if self.skip_long { self.wire.read_line_or_skip()? } else { Some(self.wire.read_line()?) }; + let Some(line) = line else { + self.skipped = true; + self.text_seen = self.text_seen.saturating_add(crate::MAX_LINE); + if self.text_seen > self.text_cap { + return Err(ProtoError::Protocol(said!("the server sent too much in answer to one command"))); + } + continue; + }; + self.text_seen = self.text_seen.saturating_add(line.len()).saturating_add(2); + return Ok(line); + } + } + + fn read_response(&mut self) -> Result { + let line = self.read_text()?; + if log::log_enabled!(log::Level::Trace) { + log::trace!("S: {}", for_trace(&self.secrets.hide(&String::from_utf8_lossy(&line)))); + } + if line.first() == Some(&b'+') { + return Ok(Response::GoAhead); + } + let Some(rest) = line.strip_prefix(b"* ") else { + // Tagged: `A0001 OK done`. + let text = String::from_utf8_lossy(&line); + let mut words = text.splitn(3, ' '); + let (tag, word, rest) = (words.next().unwrap_or(""), words.next().unwrap_or(""), words.next().unwrap_or("")); + return match Status::parse(word) { + Some(status) if !tag.is_empty() && tag != "*" => { + Ok(Response::Status { tag: Some(tag.to_string()), line: StatusLine::new(status, rest) }) + } + _ => Err(ProtoError::Protocol(said!("\"{line}\" is not an IMAP response", line = tidy(&self.secrets.hide(&text))))), + }; + }; + // `* OK …`, `* BYE …`: the rest is text for people, where `{5}` is no literal. + let word_end = rest.iter().position(|b| *b == b' ').unwrap_or(rest.len()); + let word = String::from_utf8_lossy(rest.get(..word_end).unwrap_or(&[])); + if let Some(status) = Status::parse(&word) { + let text = String::from_utf8_lossy(rest.get(word_end..).unwrap_or(&[])); + return Ok(Response::Status { tag: None, line: StatusLine::new(status, &text) }); + } + // Data: a line, and for as long as a line ends in `{n}`, n bytes and another line. + let mut pieces = Vec::new(); + let mut text = rest.to_vec(); + let (mut text_bytes, mut literal_bytes) = (text.len(), 0usize); + for _ in 0..=MAX_LITERALS { + let Some((_, claimed)) = parse::literal_marker(&text) else { + pieces.push(Piece::Text(text)); + return Ok(Response::Data(parse::values(pieces)?)); + }; + let size = usize::try_from(claimed).ok().filter(|n| literal_bytes.saturating_add(*n) <= MAX_LITERAL).ok_or_else(|| { + ProtoError::Protocol(said!( + "the server sent {claimed} bytes in one piece, more than the {mb} MB MailCraft accepts", + claimed, + mb = MAX_LITERAL >> 20 + )) + })?; + let literal = self.wire.read_block(size)?; + literal_bytes = literal_bytes.saturating_add(size); + log::trace!("S: ({size} bytes)"); + pieces.push(Piece::Text(text)); + pieces.push(Piece::Literal(literal)); + text = self.read_text()?; + text_bytes = text_bytes.saturating_add(text.len()); + if text_bytes > MAX_TEXT { + return Err(ProtoError::Protocol(said!("the server's response is too long"))); + } + } + Err(ProtoError::Protocol(said!("the server's response has too many parts"))) + } + + /// Keep what a status line says in its response code. + fn note_status(&mut self, line: &StatusLine) { + match line.code.as_str() { + "UIDVALIDITY" => self.selected.uid_validity = line.arg.parse().unwrap_or(0), + "UIDNEXT" => self.selected.uid_next = line.arg.parse().unwrap_or(0), + "COPYUID" if self.copied.len() < 2 => self.copied.push(copied_from(&line.arg)), + "APPENDUID" if self.appended.len() < 2 => self.appended.push(appended_from(&line.arg)), + "CAPABILITY" => self.capabilities = Some(line.arg.split_whitespace().take(MAX_CAPABILITIES).map(str::to_ascii_uppercase).collect()), + _ => {} + } + } + + /// Keep what untagged data says about the session, whichever command it arrives during. + fn note_data(&mut self, values: &[Value]) { + match (values.first().and_then(Value::atom), values.get(1).and_then(Value::atom)) { + (Some(count), Some(word)) if word.eq_ignore_ascii_case("EXISTS") => self.selected.exists = count.parse().unwrap_or(0), + (Some(word), _) if word.eq_ignore_ascii_case("CAPABILITY") => { + self.capabilities = Some(values.iter().skip(1).filter_map(Value::atom).take(MAX_CAPABILITIES).map(str::to_ascii_uppercase).collect()); + } + _ => {} + } + } + + /// The server's own words for why it said no, fit to show. + /// What the server said for itself, as it said it; MailCraft's words when it said nothing. + fn refusal(&self, line: &StatusLine) -> Text { + // Hidden before it is shortened: a secret cut in half would no longer be recognised. + let text = tidy(&self.secrets.hide(&line.text)); + if text.is_empty() { said!("the command was refused") } else { Text::verbatim(text) } + } +} + +#[cfg(test)] +mod gmail_labels_tests; +#[cfg(test)] +mod gmail_tests; +#[cfg(test)] +mod limits_tests; +#[cfg(test)] +mod tests; diff --git a/crates/proto/src/imap/parse.rs b/crates/proto/src/imap/parse.rs new file mode 100644 index 000000000..f18ba9299 --- /dev/null +++ b/crates/proto/src/imap/parse.rs @@ -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), + Literal(Vec), +} + +/// 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), + List(Vec), +} + +impl Value { + pub(crate) fn atom(&self) -> Option<&str> { + match self { + Value::Atom(a) => Some(a), + _ => None, + } + } + + pub(crate) fn number(&self) -> Option { + 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 { + 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) -> Result, ProtoError> { + // The list being filled is on top; the response itself is at the bottom. + let mut stack: Vec> = 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) { + if let Some(top) = stack.last_mut() { + top.push(value); + } +} + +fn close(stack: &mut Vec>) { + if stack.len() > 1 + && let Some(list) = stack.pop() + { + push(stack, Value::List(list)); + } +} + +fn scan(text: &[u8], stack: &mut Vec>) -> 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, 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 { + 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 { + 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 { + 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); + } +} diff --git a/crates/proto/src/imap/password.rs b/crates/proto/src/imap/password.rs new file mode 100644 index 000000000..acc7d0ec0 --- /dev/null +++ b/crates/proto/src/imap/password.rs @@ -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 Imap { + /// 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))), + } + } +} diff --git a/crates/proto/src/imap/password_tests.rs b/crates/proto/src/imap/password_tests.rs new file mode 100644 index 000000000..cbd0989fc --- /dev/null +++ b/crates/proto/src/imap/password_tests.rs @@ -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()); + } +} diff --git a/crates/proto/src/imap/status.rs b/crates/proto/src/imap/status.rs new file mode 100644 index 000000000..3c378308a --- /dev/null +++ b/crates/proto/src/imap/status.rs @@ -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) -> Option { + 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 Imap { + /// STATUS of one mailbox; `None` when the server refuses or leaves a count out. + pub fn status(&mut self, raw_name: &str) -> Result, 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>, 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>, 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> = 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) + } +} diff --git a/crates/proto/src/imap/status_tests.rs b/crates/proto/src/imap/status_tests.rs new file mode 100644 index 000000000..a0f252b35 --- /dev/null +++ b/crates/proto/src/imap/status_tests.rs @@ -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::(), 0..600), names in 0usize..120) { + let list: Vec = (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"); + } +} diff --git a/crates/proto/src/imap/tests.rs b/crates/proto/src/imap/tests.rs new file mode 100644 index 000000000..c384d0154 --- /dev/null +++ b/crates/proto/src/imap/tests.rs @@ -0,0 +1,1068 @@ +// 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}; + +fn mailbox(name: &str, raw: &str, delimiter: Option, flags: &[&str]) -> Mailbox { + Mailbox { name: name.into(), raw: raw.into(), delimiter, flags: flags.iter().map(|f| f.to_string()).collect() } +} + +fn fetched(uid: u32, flags: &[&str]) -> Fetched { + Fetched { uid, flags: flags.iter().map(|f| f.to_string()).collect(), internal_date: None, body: None, gmail_id: None, gmail_labels: None } +} + +/// A FETCH response carrying `body` as a literal, between `before` and `after`. +fn with_literal(before: &str, body: &[u8], after: &str) -> Vec { + let mut out = format!("{before}{{{}}}\r\n", body.len()).into_bytes(); + out.extend_from_slice(body); + out.extend_from_slice(after.as_bytes()); + out +} + +#[test] +fn greetings() { + let mut s = Script::new("* OK [CAPABILITY IMAP4rev1 STARTTLS] mail.example.org ready\r\n"); + let imap = Imap::connect(&mut s).unwrap(); + assert!(!imap.is_authenticated()); + assert_eq!(imap.capabilities, Some(vec!["IMAP4REV1".to_string(), "STARTTLS".to_string()])); + + let mut s = Script::new("* PREAUTH welcome back\r\n"); + assert!(Imap::connect(&mut s).unwrap().is_authenticated()); + + let mut s = Script::new("* BYE overloaded, try later\r\n"); + assert_eq!(Imap::connect(&mut s).unwrap_err(), ProtoError::Rejected("overloaded, try later".into())); + + for junk in ["hello\r\n", "+ go on\r\n", "* 3 EXISTS\r\n", "A0001 OK early\r\n", "* NO\r\n", "\r\n", "*\r\n", "220 smtp.example.org ESMTP\r\n"] { + let mut s = Script::new(junk); + assert!(matches!(Imap::connect(&mut s), Err(ProtoError::Protocol(_))), "{junk:?}"); + } + let mut s = Script::new(""); + assert!(matches!(Imap::connect(&mut s), Err(ProtoError::Io(_)))); +} + +#[test] +fn capabilities_are_upper_cased() { + let mut s = Script::new( + "* CAPABILITY IMAP4rev1 StartTLS special-use AUTH=PLAIN\r\nA0001 OK done\r\nA0002 OK [CAPABILITY IMAP4rev1 IDLE] done\r\nA0003 OK none\r\n", + ); + let mut imap = Imap::resume(&mut s); + assert_eq!(imap.capabilities().unwrap(), ["IMAP4REV1", "STARTTLS", "SPECIAL-USE", "AUTH=PLAIN"]); + // Some servers answer in the tagged line. + assert_eq!(imap.capabilities().unwrap(), ["IMAP4REV1", "IDLE"]); + assert_eq!(imap.capabilities().unwrap(), Vec::::new()); + assert_eq!(s.sent(), "A0001 CAPABILITY\r\nA0002 CAPABILITY\r\nA0003 CAPABILITY\r\n"); +} + +#[test] +fn login_quotes_its_strings() { + let mut s = Script::new("A0001 OK [CAPABILITY IMAP4rev1] welcome\r\n"); + let mut imap = Imap::resume(&mut s); + imap.login(r#"ada "the" \ lovelace"#, r#"p"w\d {5}"#).unwrap(); + assert!(imap.is_authenticated()); + assert_eq!(s.sent(), "A0001 LOGIN \"ada \\\"the\\\" \\\\ lovelace\" \"p\\\"w\\\\d {5}\"\r\n"); +} + +#[test] +fn login_sends_what_quotes_cannot_carry_as_literals() { + let mut s = Script::new("+ go on\r\nA0001 OK welcome\r\n"); + let mut imap = Imap::resume(&mut s); + imap.login("ada", "pässwörd").unwrap(); + assert_eq!(s.sent(), "A0001 LOGIN \"ada\" {10}\r\npässwörd\r\n"); + + // Both as literals, each after its own go-ahead; a line break can't end the command early. + let mut s = Script::new("+ go on\r\n+ go on\r\nA0001 OK welcome\r\n"); + let mut imap = Imap::resume(&mut s); + imap.login("ädä", "two\r\nA0002 LOGOUT").unwrap(); + assert_eq!(s.sent(), "A0001 LOGIN {5}\r\nädä {17}\r\ntwo\r\nA0002 LOGOUT\r\n"); + + // A very long password too. + let long = "x".repeat(MAX_QUOTED + 1); + let mut s = Script::new("+ go on\r\nA0001 OK welcome\r\n"); + Imap::resume(&mut s).login("ada", &long).unwrap(); + assert!(s.sent().starts_with("A0001 LOGIN \"ada\" {1001}\r\nxxx")); +} + +#[test] +fn a_wrong_password_is_an_auth_error_that_never_shows_it() { + // A careless server repeats what it was sent. + let mut s = Script::new("A0001 NO [AUTHENTICATIONFAILED] no user ada with password hunter2\r\n"); + let mut imap = Imap::resume(&mut s); + let err = imap.login("ada", "hunter2").unwrap_err(); + assert_eq!(err, ProtoError::Auth("[AUTHENTICATIONFAILED] no user ada with password ***".into())); + assert!(!imap.is_authenticated()); + assert!(!format!("{err} {err:?} {imap:?}").contains("hunter2")); + + // BAD is not about the password. + let mut s = Script::new("A0001 BAD what\r\n"); + assert_eq!(Imap::resume(&mut s).login("ada", "hunter2"), Err(ProtoError::Rejected("what".into()))); + + // Refused before the literal went out: the password is never sent. + let mut s = Script::new("A0001 NO no literals here\r\n"); + assert!(matches!(Imap::resume(&mut s).login("ada", "pässwörd"), Err(ProtoError::Auth(_)))); + assert_eq!(s.sent(), "A0001 LOGIN \"ada\" {10}\r\n"); + + // Nothing at all is sent when it can't be. + let mut s = Script::new("A0001 OK welcome\r\n"); + assert!(matches!(Imap::resume(&mut s).login("ada", "nul\0"), Err(ProtoError::Auth(_)))); + assert_eq!(s.sent(), ""); +} + +#[test] +fn no_password_for_a_server_that_disabled_login() { + let mut s = Script::new("* OK [CAPABILITY IMAP4rev1 STARTTLS LOGINDISABLED] ready\r\nA0001 OK welcome\r\n"); + let mut imap = Imap::connect(&mut s).unwrap(); + assert!(matches!(imap.login("ada", "hunter2"), Err(ProtoError::Auth(_)))); + assert_eq!(s.sent(), ""); +} + +const TOKEN: &str = "tok.en-123"; + +/// What goes out for `ada@example.org` with [`TOKEN`]. +fn bearer() -> String { + let payload = xoauth2("ada@example.org", TOKEN).unwrap(); + assert_eq!(payload, "dXNlcj1hZGFAZXhhbXBsZS5vcmcBYXV0aD1CZWFyZXIgdG9rLmVuLTEyMwEB"); + payload +} + +#[test] +fn a_token_goes_with_the_command_when_the_server_takes_it_that_way() { + let mut s = Script::new("* OK [CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN AUTH=XOAUTH2] ready\r\nA0001 OK [CAPABILITY IMAP4rev1 IDLE] welcome\r\n"); + let mut imap = Imap::connect(&mut s).unwrap(); + imap.authenticate_xoauth2("ada@example.org", TOKEN).unwrap(); + assert!(imap.is_authenticated()); + // What the server can do once signed in is noted. + assert_eq!(imap.capabilities, Some(vec!["IMAP4REV1".to_string(), "IDLE".to_string()])); + assert_eq!(s.sent(), format!("A0001 AUTHENTICATE XOAUTH2 {}\r\n", bearer())); + assert!(s.finished()); +} + +#[test] +fn a_token_waits_for_the_go_ahead_otherwise() { + // A server that hasn't said what it can do, one without SASL-IR, and one that has SASL-IR + // but didn't list the mechanism: each is asked first. + for greeting in ["", "* OK [CAPABILITY IMAP4rev1 AUTH=XOAUTH2] ready\r\n", "* OK [CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN] ready\r\n"] { + let mut s = Script::new(format!("{greeting}+ \r\n* CAPABILITY IMAP4rev1 IDLE\r\nA0001 OK welcome\r\n")); + let mut imap = if greeting.is_empty() { Imap::resume(&mut s) } else { Imap::connect(&mut s).unwrap() }; + imap.authenticate_xoauth2("ada@example.org", TOKEN).unwrap(); + assert!(imap.is_authenticated(), "{greeting:?}"); + assert_eq!(s.sent(), format!("A0001 AUTHENTICATE XOAUTH2\r\n{}\r\n", bearer()), "{greeting:?}"); + } +} + +#[test] +fn a_refused_token_is_an_auth_error_that_never_shows_it() { + let payload = bearer(); + let caps = "* OK [CAPABILITY IMAP4rev1 SASL-IR AUTH=XOAUTH2] ready\r\n"; + // The reasons come first (JSON in base64) and the verdict after an empty line; a careless + // server repeats what it was sent. + let reasons = "+ eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIiwic2NvcGUiOiJodHRwczovL21haWwuZXhhbXBsZS5vcmcvIn0=\r\n"; + let mut s = Script::new(format!("{caps}{reasons}A0001 NO [AUTHENTICATIONFAILED] no good: {TOKEN} ({payload})\r\n")); + let mut imap = Imap::connect(&mut s).unwrap(); + let err = imap.authenticate_xoauth2("ada@example.org", TOKEN).unwrap_err(); + assert_eq!(err, ProtoError::Auth("[AUTHENTICATIONFAILED] no good: *** (***)".into())); + assert!(!imap.is_authenticated()); + assert!(!format!("{err} {err:?} {imap:?}").contains(TOKEN)); + assert_eq!(s.sent(), format!("A0001 AUTHENTICATE XOAUTH2 {payload}\r\n\r\n")); + assert!(s.finished()); + + // The same after a go-ahead. + let mut s = Script::new(format!("+ \r\n{reasons}A0001 NO AUTHENTICATE failed.\r\n")); + let mut imap = Imap::resume(&mut s); + assert_eq!(imap.authenticate_xoauth2("ada@example.org", TOKEN), Err(ProtoError::Auth("AUTHENTICATE failed.".into()))); + assert_eq!(s.sent(), format!("A0001 AUTHENTICATE XOAUTH2\r\n{payload}\r\n\r\n")); + + // Refused in one word, without reasons. + let mut s = Script::new("+ \r\nA0001 NO AUTHENTICATE failed.\r\n"); + assert_eq!(Imap::resume(&mut s).authenticate_xoauth2("ada@example.org", TOKEN), Err(ProtoError::Auth("AUTHENTICATE failed.".into()))); + assert_eq!(s.sent(), format!("A0001 AUTHENTICATE XOAUTH2\r\n{payload}\r\n")); + + // A token echoed in a long answer is hidden before the answer is shortened. + let long = format!("head.{}.tail", "x".repeat(2_000)); + let mut s = Script::new(format!("+ \r\nA0001 NO {} bad token {long}\r\n", "no ".repeat(80))); + let err = Imap::resume(&mut s).authenticate_xoauth2("ada@example.org", &long).unwrap_err(); + let shown = format!("{err} {err:?}"); + assert!(matches!(err, ProtoError::Auth(_))); + assert!(!shown.contains("head.") && !shown.contains("xxxx"), "{shown}"); +} + +#[test] +fn a_server_without_the_mechanism_never_sees_the_token() { + for (server, expected) in [ + ("A0001 NO [CANNOT] unsupported authentication mechanism\r\n", ProtoError::Auth("[CANNOT] unsupported authentication mechanism".into())), + ("A0001 BAD what\r\n", ProtoError::Rejected("what".into())), + // "Signed in" without having been shown anything can't be true. + ("A0001 OK welcome\r\n", ProtoError::Protocol(said!("the server ended the command early"))), + ] { + let mut s = Script::new(format!("* OK [CAPABILITY IMAP4rev1 AUTH=PLAIN] ready\r\n{server}")); + let mut imap = Imap::connect(&mut s).unwrap(); + assert_eq!(imap.authenticate_xoauth2("ada@example.org", TOKEN), Err(expected), "{server:?}"); + assert!(!imap.is_authenticated()); + assert_eq!(s.sent(), "A0001 AUTHENTICATE XOAUTH2\r\n", "{server:?}"); + } +} + +#[test] +fn questions_a_token_has_no_answer_to_end_the_sign_in() { + // After the reasons, another question: the exchange is cancelled. + let mut s = Script::new("+ \r\n+ e30=\r\n+ more?\r\nA0001 BAD cancelled\r\n"); + let mut imap = Imap::resume(&mut s); + assert!(matches!(imap.authenticate_xoauth2("ada@example.org", TOKEN), Err(ProtoError::Auth(_)))); + assert!(s.sent().ends_with("\r\n\r\n*\r\n")); + // A server that calls a cancelled exchange a success is not believed. + let mut s = Script::new("+ \r\n+ e30=\r\n+ more?\r\nA0001 OK welcome\r\n"); + let mut imap = Imap::resume(&mut s); + assert!(matches!(imap.authenticate_xoauth2("ada@example.org", TOKEN), Err(ProtoError::Auth(_)))); + assert!(!imap.is_authenticated()); + // One that never stops asking. + let mut s = Script::new("+ \r\n".repeat(50)); + assert!(matches!(Imap::resume(&mut s).authenticate_xoauth2("ada@example.org", TOKEN), Err(ProtoError::Protocol(_)))); + assert_eq!(s.sent().matches("\r\n").count(), 4); +} + +#[test] +fn a_token_or_name_that_cannot_be_sent_is_refused() { + let mut s = Script::new("+ \r\nA0001 OK welcome\r\n"); + let mut imap = Imap::resume(&mut s); + for (user, token) in + [("ada", ""), ("ada", "tok\r\nA0002 LOGOUT"), ("ada", "tok\x01"), ("ada\x01auth=Bearer x", "tok"), ("a\0da", "tok"), ("ada\n", "tok")] + { + assert!(matches!(imap.authenticate_xoauth2(user, token), Err(ProtoError::Auth(_))), "{user:?} {token:?}"); + } + assert!(!imap.is_authenticated()); + assert_eq!(s.sent(), ""); +} + +#[test] +fn mailboxes_are_listed_with_names_in_every_form() { + let mut server = String::new(); + server += "* LIST (\\HasNoChildren) \"/\" INBOX\r\n"; + server += "* LIST (\\HasNoChildren \\Sent) \"/\" \"Sent Items\"\r\n"; + server += "* LIST (\\Noselect \\HasChildren) \"/\" \"[Gmail]\"\r\n"; + server += "* LIST (\\HasNoChildren \\Trash) \"/\" [Gmail]/Trash\r\n"; + server += "* LIST () NIL \"Entw&APw-rfe\"\r\n"; + server += "* LIST (\\HasNoChildren) \".\" {12}\r\nINBOX.&Jjo-!\r\n"; + server += "* LIST () \"/\" \"quoted \\\"name\\\" \\\\ here\"\r\n"; + server += "* LSUB () \"/\" subscribed\r\n"; + server += "* 5 EXISTS\r\n"; + server += "* LIST (\\HasNoChildren) \"/\" INBOX\r\n"; + server += "* LIST broken\r\n"; + server += "A0001 OK done\r\n"; + let mut s = Script::new(server); + let list = Imap::resume(&mut s).list().unwrap(); + assert_eq!(s.sent(), "A0001 LIST \"\" \"*\"\r\n"); + assert_eq!( + list, + [ + mailbox("INBOX", "INBOX", Some('/'), &["\\HasNoChildren"]), + mailbox("Sent Items", "Sent Items", Some('/'), &["\\HasNoChildren", "\\Sent"]), + mailbox("[Gmail]", "[Gmail]", Some('/'), &["\\Noselect", "\\HasChildren"]), + mailbox("[Gmail]/Trash", "[Gmail]/Trash", Some('/'), &["\\HasNoChildren", "\\Trash"]), + mailbox("Entwürfe", "Entw&APw-rfe", None, &[]), + mailbox("INBOX.☺!", "INBOX.&Jjo-!", Some('.'), &["\\HasNoChildren"]), + mailbox("quoted \"name\" \\ here", "quoted \"name\" \\ here", Some('/'), &[]), + ] + ); + assert!(list[2].has_flag("\\NOSELECT") && !list[0].has_flag("\\Noselect")); +} + +#[test] +fn opening_a_mailbox() { + let mut server = String::new(); + server += "* 172 EXISTS\r\n* 1 RECENT\r\n* OK [UNSEEN 12] Message 12 is first unseen\r\n"; + server += "* OK [UIDVALIDITY 3857529045] UIDs valid\r\n* OK [UIDNEXT 4392] Predicted next UID\r\n"; + server += "* FLAGS (\\Answered \\Flagged \\Deleted \\Seen \\Draft)\r\n* OK [PERMANENTFLAGS ()] No permanent flags permitted\r\n"; + server += "A0001 OK [READ-ONLY] EXAMINE completed\r\n"; + // The next one is empty and says little. + server += "* 0 EXISTS\r\n* OK [UIDVALIDITY 7]\r\nA0002 OK [READ-WRITE] SELECT completed\r\n"; + server += "A0003 NO [NONEXISTENT] no such mailbox\r\n"; + server += "+ go on\r\n* 3 EXISTS\r\n* OK [UIDVALIDITY 99999999999] too large to be one\r\nA0004 OK done\r\n"; + let mut s = Script::new(server); + let mut imap = Imap::resume(&mut s); + assert_eq!(imap.select("Sent Items", true).unwrap(), Selected { exists: 172, uid_validity: 3_857_529_045, uid_next: 4392 }); + assert_eq!(imap.select("INBOX", false).unwrap(), Selected { exists: 0, uid_validity: 7, uid_next: 0 }); + assert_eq!(imap.select("Nowhere", true), Err(ProtoError::Rejected("[NONEXISTENT] no such mailbox".into()))); + // A name the server wrote in UTF-8 goes back as a literal. + assert_eq!(imap.select("Entwürfe", true).unwrap(), Selected { exists: 3, uid_validity: 0, uid_next: 0 }); + assert_eq!(s.sent(), "A0001 EXAMINE \"Sent Items\"\r\nA0002 SELECT \"INBOX\"\r\nA0003 EXAMINE \"Nowhere\"\r\nA0004 EXAMINE {9}\r\nEntwürfe\r\n"); +} + +#[test] +fn flags_of_every_message_with_other_news_in_between() { + let mut server = String::new(); + server += "* 1 FETCH (UID 4 FLAGS (\\Seen \\Answered))\r\n"; + server += "* 2 FETCH (FLAGS (\\Flagged $Forwarded) UID 7)\r\n"; + server += "* 3 EXPUNGE\r\n* 9 EXISTS\r\n* 1 RECENT\r\n* FLAGS (\\Seen)\r\n"; + // Text for people may end like a literal without being one. + server += "* OK [ALERT] still here {5}\r\n"; + // Without a UID there is no telling which message this is. + server += "* 4 FETCH (FLAGS (\\Deleted))\r\n"; + server += "* 3 FETCH (UID 9 FLAGS ())\r\n"; + // The later word about a message counts. + server += "* 2 FETCH (UID 7 FLAGS (\\Seen))\r\n"; + // A message named without its flags is there all the same, and one named again keeps the flags it had. + server += "* 5 FETCH (UID 2 RFC822.SIZE 100)\r\n"; + server += "* 1 FETCH (UID 4)\r\n"; + server += "A0001 OK done\r\n"; + let mut s = Script::new(server); + let got = Imap::resume(&mut s).uid_fetch_flags("1:*").unwrap(); + assert_eq!(got, [fetched(2, &[]), fetched(4, &["\\Seen", "\\Answered"]), fetched(7, &["\\Seen"]), fetched(9, &[])]); + assert_eq!(s.sent(), "A0001 UID FETCH 1:* (UID FLAGS)\r\n"); + + let mut s = Script::new("A0001 OK nothing there\r\n"); + assert_eq!(Imap::resume(&mut s).uid_fetch_flags("5,9,12:20").unwrap(), []); + assert_eq!(s.sent(), "A0001 UID FETCH 5,9,12:20 (UID FLAGS)\r\n"); +} + +#[test] +fn sizes() { + let mut s = + Script::new("* 2 FETCH (RFC822.SIZE 99999999999 UID 9)\r\n* 1 FETCH (UID 4 RFC822.SIZE 2048)\r\n* 3 FETCH (UID 5)\r\nA0001 OK done\r\n"); + assert_eq!(Imap::resume(&mut s).uid_fetch_sizes("4:9").unwrap(), [(4, 2048), (9, 99_999_999_999)]); + assert_eq!(s.sent(), "A0001 UID FETCH 4:9 (UID RFC822.SIZE)\r\n"); +} + +#[test] +fn sets_that_are_not_sets_are_never_sent() { + for bad in ["", "1:* (BODY[])", "1 2", "a", "1:*\r\nA0002 LOGOUT"] { + let mut s = Script::new("A0001 OK done\r\n"); + let mut imap = Imap::resume(&mut s); + assert!(matches!(imap.uid_fetch_flags(bad), Err(ProtoError::Protocol(_))), "{bad:?}"); + assert!(matches!(imap.uid_fetch_sizes(bad), Err(ProtoError::Protocol(_))), "{bad:?}"); + assert_eq!(s.sent(), "", "{bad:?}"); + } +} + +#[test] +fn a_message_arrives_whole_whatever_is_in_it() { + // A body full of things that look like protocol. + let body = b"Subject: Hi\r\n\r\nA0001 OK fake\r\n* 1 FETCH (UID 2)\r\n{5}\r\n\"(\\\r\n)"; + let mut server = with_literal("* 5 FETCH (UID 12 FLAGS (\\Seen $Forwarded) INTERNALDATE \"17-Jul-1996 02:44:25 -0700\" BODY[] ", body, ")\r\n"); + server.extend_from_slice(b"A0001 OK done\r\n"); + let mut s = Script::new(server); + let got = Imap::resume(&mut s).uid_fetch_message(12).unwrap().unwrap(); + assert_eq!( + got, + Fetched { + uid: 12, + flags: vec!["\\Seen".into(), "$Forwarded".into()], + internal_date: Some("17-Jul-1996 02:44:25 -0700".into()), + body: Some(body.to_vec()), + gmail_id: None, + gmail_labels: None + } + ); + assert_eq!(s.sent(), "A0001 UID FETCH 12 (UID FLAGS INTERNALDATE BODY.PEEK[])\r\n"); + assert!(s.finished()); +} + +#[test] +fn fetch_items_come_in_any_order() { + let body = b"From: ada@example.org\r\n\r\nBody\r\n"; + let mut server = with_literal( + "* 5 FETCH (BODY[] ", + body, + " INTERNALDATE \" 7-Jul-1996 02:44:25 +0000\" RFC822.SIZE 31 FLAGS () UID 12 X-UNKNOWN (a (b)))\r\n", + ); + server.extend_from_slice(b"A0001 OK done\r\n"); + let mut s = Script::new(server); + let got = Imap::resume(&mut s).uid_fetch_message(12).unwrap().unwrap(); + assert_eq!( + (got.uid, got.flags.len(), got.internal_date.as_deref(), got.body.as_deref()), + (12, 0, Some(" 7-Jul-1996 02:44:25 +0000"), Some(&body[..])) + ); +} + +#[test] +fn bodies_at_the_edges() { + // Empty, as a literal of no bytes. + let mut s = Script::new("* 1 FETCH (UID 3 BODY[] {0}\r\n)\r\nA0001 OK done\r\n"); + assert_eq!(Imap::resume(&mut s).uid_fetch_message(3).unwrap().unwrap().body, Some(Vec::new())); + // Short, in quotes. + let mut s = Script::new("* 1 FETCH (UID 3 BODY[] \"tiny \\\"body\\\"\")\r\nA0001 OK done\r\n"); + assert_eq!(Imap::resume(&mut s).uid_fetch_message(3).unwrap().unwrap().body, Some(b"tiny \"body\"".to_vec())); + // Under its old name. + let mut s = Script::new("* 1 FETCH (UID 3 RFC822 {2}\r\nok)\r\nA0001 OK done\r\n"); + assert_eq!(Imap::resume(&mut s).uid_fetch_message(3).unwrap().unwrap().body, Some(b"ok".to_vec())); + // Flags in one response, the body in another. + let mut s = Script::new("* 1 FETCH (UID 3 FLAGS (\\Seen))\r\n* 1 FETCH (UID 3 BODY[] {2}\r\nok)\r\nA0001 OK done\r\n"); + let got = Imap::resume(&mut s).uid_fetch_message(3).unwrap().unwrap(); + assert_eq!((got.flags, got.body), (vec!["\\Seen".to_string()], Some(b"ok".to_vec()))); + // A megabyte in one piece. + let big = vec![b'x'; 1 << 20]; + let mut server = with_literal("* 1 FETCH (UID 3 BODY[] ", &big, ")\r\n"); + server.extend_from_slice(b"A0001 OK done\r\n"); + let mut s = Script::whole(server); + assert_eq!(Imap::resume(&mut s).uid_fetch_message(3).unwrap().unwrap().body, Some(big)); +} + +#[test] +fn a_message_that_is_gone_is_none() { + for server in [ + "A0001 OK nothing\r\n", + "* 1 FETCH (UID 3 BODY[] NIL)\r\nA0001 OK done\r\n", + "* 1 FETCH (UID 3 FLAGS (\\Seen))\r\nA0001 OK done\r\n", + "* 1 FETCH (UID 4 BODY[] {2}\r\nno)\r\n* 2 EXPUNGE\r\nA0001 OK done\r\n", + "* 1 FETCH (BODY[] {2}\r\nno)\r\nA0001 OK done\r\n", + ] { + let mut s = Script::new(server); + assert_eq!(Imap::resume(&mut s).uid_fetch_message(3), Ok(None), "{server:?}"); + } + // There is no message 0 to ask for. + let mut s = Script::new(""); + assert_eq!(Imap::resume(&mut s).uid_fetch_message(0), Ok(None)); + assert_eq!(s.sent(), ""); + let mut s = Script::new("A0001 NO [SERVERBUG] can't read it\r\n"); + assert_eq!(Imap::resume(&mut s).uid_fetch_message(3), Err(ProtoError::Rejected("[SERVERBUG] can't read it".into()))); +} + +#[test] +fn a_header_arrives_alone() { + let header = b"From: ada@example.org\r\nSubject: Sixty megabytes\r\n\r\n"; + let mut server = with_literal("* 5 FETCH (UID 12 FLAGS (\\Seen) INTERNALDATE \"17-Jul-1996 02:44:25 -0700\" BODY[HEADER] ", header, ")\r\n"); + server.extend_from_slice(b"A0001 OK done\r\n"); + let mut s = Script::new(server); + let got = Imap::resume(&mut s).uid_fetch_header(12).unwrap().unwrap(); + assert_eq!( + got, + Fetched { + uid: 12, + flags: vec!["\\Seen".into()], + internal_date: Some("17-Jul-1996 02:44:25 -0700".into()), + body: Some(header.to_vec()), + gmail_id: None, + gmail_labels: None + } + ); + assert_eq!(s.sent(), "A0001 UID FETCH 12 (UID FLAGS INTERNALDATE BODY.PEEK[HEADER])\r\n"); + assert!(s.finished()); + // Under its old name, and empty. + let mut s = Script::new("* 1 FETCH (UID 3 RFC822.HEADER {2}\r\n\r\n)\r\nA0001 OK done\r\n"); + assert_eq!(Imap::resume(&mut s).uid_fetch_header(3).unwrap().unwrap().body, Some(b"\r\n".to_vec())); + // A server that sends the whole message when asked for its header is not taken at its word, + // nor is a header taken for a message. + let mut s = Script::new("* 1 FETCH (UID 3 BODY[] {2}\r\nok)\r\nA0001 OK done\r\n"); + assert_eq!(Imap::resume(&mut s).uid_fetch_header(3), Ok(None)); + let mut s = Script::new("* 1 FETCH (UID 3 BODY[HEADER] {2}\r\nok)\r\nA0001 OK done\r\n"); + assert_eq!(Imap::resume(&mut s).uid_fetch_message(3), Ok(None)); + // Gone, never there, refused. + let mut s = Script::new("A0001 OK nothing\r\n"); + assert_eq!(Imap::resume(&mut s).uid_fetch_header(3), Ok(None)); + let mut s = Script::new(""); + assert_eq!(Imap::resume(&mut s).uid_fetch_header(0), Ok(None)); + assert_eq!(s.sent(), ""); + let mut s = Script::new("A0001 NO [SERVERBUG] can't read it\r\n"); + assert_eq!(Imap::resume(&mut s).uid_fetch_header(3), Err(ProtoError::Rejected("[SERVERBUG] can't read it".into()))); + // A header as large as no header is: refused unread, like a message. + let mut s = Script::new(format!("* 1 FETCH (UID 3 BODY[HEADER] {{{}}}\r\nxxxx", MAX_LITERAL + 1)); + assert!(matches!(Imap::resume(&mut s).uid_fetch_header(3), Err(ProtoError::Protocol(_)))); +} + +#[test] +fn the_stream_can_be_reached_between_commands() { + let mut s = Script::new("A0001 OK done\r\nA0002 OK done\r\n"); + let mut imap = Imap::resume(&mut s); + imap.select("INBOX", true).unwrap(); + // Looked at, not read from: the session goes on where it was. + assert_eq!(imap.get_mut().sent(), "A0001 EXAMINE \"INBOX\"\r\n"); + imap.select("Sent", true).unwrap(); + assert!(s.finished()); +} + +#[test] +fn oversized_literals_are_refused_unread() { + for size in [(MAX_LITERAL + 1).to_string(), "99999999999999999999999999".to_string(), u64::MAX.to_string()] { + let mut s = Script::new(format!("* 1 FETCH (UID 3 BODY[] {{{size}}}\r\nxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")); + let err = Imap::resume(&mut s).uid_fetch_message(3).unwrap_err(); + assert!(matches!(&err, ProtoError::Protocol(text) if text.to_string().contains("64 MB")), "{err:?}"); + // The x's were not read as if they were the message. + assert!(!s.finished()); + } + // Several literals that are only too much together. + let mut s = Script::new(format!("* 1 FETCH (A {{2}}\r\nab B {{{}}}\r\n", MAX_LITERAL - 1)); + assert!(matches!(Imap::resume(&mut s).uid_fetch_message(3), Err(ProtoError::Protocol(_)))); +} + +#[test] +fn responses_without_end_are_refused() { + // More literals than any response has. + let mut s = Script::whole(format!("* 1 FETCH ({}", "X {0}\r\n ".repeat(MAX_LITERALS + 2))); + assert_eq!(Imap::resume(&mut s).uid_fetch_message(3), Err(ProtoError::Protocol(said!("the server's response has too many parts")))); + // More text than any response has. + let line = format!("{} {{0}}\r\n", "x".repeat(MAX_LINE - 100)); + let mut s = Script::whole(format!("* 1 FETCH ({}", line.repeat(6))); + assert_eq!(Imap::resume(&mut s).uid_fetch_message(3), Err(ProtoError::Protocol(said!("the server's response is too long")))); + // A line that never ends. + let mut s = Script::whole(format!("* 1 FETCH ({}", "x".repeat(MAX_LINE * 2))); + assert!(matches!(Imap::resume(&mut s).uid_fetch_message(3), Err(ProtoError::Protocol(_)))); + // Lists inside lists inside lists. + let mut s = Script::new(format!("* 1 FETCH {}\r\nA0001 OK done\r\n", "(".repeat(200))); + assert_eq!(Imap::resume(&mut s).uid_fetch_message(3), Err(ProtoError::Protocol(said!("the server's response is nested too deeply")))); +} + +#[test] +fn storing_flags() { + let mut s = Script::new("A0001 OK done\r\nA0002 OK done\r\nA0003 NO [READ-ONLY] mailbox is read-only\r\n"); + let mut imap = Imap::resume(&mut s); + imap.uid_store(7, true, &["\\Seen", "\\Flagged"]).unwrap(); + imap.uid_store(7, false, &["$Forwarded"]).unwrap(); + assert_eq!(imap.uid_store(8, true, &["\\Deleted"]), Err(ProtoError::Rejected("[READ-ONLY] mailbox is read-only".into()))); + assert_eq!( + s.sent(), + "A0001 UID STORE 7 +FLAGS.SILENT (\\Seen \\Flagged)\r\nA0002 UID STORE 7 -FLAGS.SILENT ($Forwarded)\r\nA0003 UID STORE 8 +FLAGS.SILENT (\\Deleted)\r\n" + ); + + // Nothing to store, or nothing to store it on: the server isn't asked. + let mut s = Script::new("A0001 OK done\r\n"); + let mut imap = Imap::resume(&mut s); + assert_eq!(imap.uid_store(7, true, &[]), Ok(())); + assert!(matches!(imap.uid_store(0, true, &["\\Seen"]), Err(ProtoError::Protocol(_)))); + assert_eq!(s.sent(), ""); + + for bad in ["", "\\", "two words", "\\Seen) (\\Deleted", "\\\\Seen", "a\r\nb", "sée"] { + let mut s = Script::new("A0001 OK done\r\n"); + let mut imap = Imap::resume(&mut s); + assert!(matches!(imap.uid_store(7, true, &[bad]), Err(ProtoError::Protocol(_))), "{bad:?}"); + assert!(matches!(imap.append("Sent", &["\\Seen", bad], b"x"), Err(ProtoError::Protocol(_))), "{bad:?}"); + assert_eq!(s.sent(), "", "{bad:?}"); + } +} + +#[test] +fn flags_are_stored_for_many_messages_at_once() { + let mut s = Script::new("A0001 OK done\r\nA0002 OK done\r\nA0003 NO [READ-ONLY] mailbox is read-only\r\n"); + let mut imap = Imap::resume(&mut s); + imap.uid_store_set("4,7:9,12", true, &["\\Seen"]).unwrap(); + imap.uid_store_set("5", false, &["\\Flagged", "\\Answered"]).unwrap(); + assert_eq!(imap.uid_store_set("6", true, &["\\Deleted"]), Err(ProtoError::Rejected("[READ-ONLY] mailbox is read-only".into()))); + assert_eq!( + s.sent(), + "A0001 UID STORE 4,7:9,12 +FLAGS.SILENT (\\Seen)\r\nA0002 UID STORE 5 -FLAGS.SILENT (\\Flagged \\Answered)\r\nA0003 UID STORE 6 +FLAGS.SILENT (\\Deleted)\r\n" + ); +} + +#[test] +fn a_set_for_a_change_names_its_messages() { + // Nothing that reaches for messages nobody looked at, and nothing that isn't a set at all. + let long = format!("1:{}", MAX_SET_UIDS + 1); + for bad in ["1:*", "*", "", "0", "5:3", "1,,2", "1:2:3", "4 5", "+4", "4,", "4\r\nA0002 EXPUNGE", "4294967296", long.as_str()] { + let mut s = Script::new("A0001 OK done\r\n"); + let mut imap = Imap::resume(&mut s); + imap.capabilities = Some(vec!["UIDPLUS".into(), "MOVE".into()]); + assert!(matches!(imap.uid_store_set(bad, true, &["\\Deleted"]), Err(ProtoError::Protocol(_))), "{bad:?}"); + assert!(matches!(imap.uid_move(bad, "Archive"), Err(ProtoError::Protocol(_))), "{bad:?}"); + assert!(matches!(imap.uid_copy(bad, "Archive"), Err(ProtoError::Protocol(_))), "{bad:?}"); + assert!(matches!(imap.uid_expunge(bad), Err(ProtoError::Protocol(_))), "{bad:?}"); + assert_eq!(s.sent(), "", "{bad:?}"); + } + // Reading may ask for everything. + let mut s = Script::new("A0001 OK done\r\n"); + assert_eq!(Imap::resume(&mut s).uid_fetch_flags("1:*").unwrap(), []); +} + +#[test] +fn moving_and_copying_say_where_the_messages_went() { + // A copy answers in its last line, a move before the messages leave (RFC 6851). + let mut server = String::new(); + server += "A0001 OK [COPYUID 38505 304,319:320 3956:3958] Done\r\n"; + server += "* OK [COPYUID 432432 42:43 1202:1203] moved\r\n* 2 EXPUNGE\r\n* 1 EXPUNGE\r\nA0002 OK Done\r\n"; + // Nothing matched, or a server without UIDPLUS: done, and nothing known. + server += "A0003 OK No messages\r\nA0004 OK done\r\n"; + server += "A0005 NO [TRYCREATE] no such mailbox\r\n"; + let mut s = Script::new(server); + let mut imap = Imap::resume(&mut s); + assert_eq!( + imap.uid_copy("304,319:320", "Archive").unwrap(), + Some(Copied { uid_validity: 38_505, uids: vec![(304, 3956), (319, 3957), (320, 3958)] }) + ); + assert_eq!(imap.uid_move("42:43", "Entw&APw-rfe").unwrap(), Some(Copied { uid_validity: 432_432, uids: vec![(42, 1202), (43, 1203)] })); + assert_eq!(imap.uid_move("99", "Archive"), Ok(None)); + assert_eq!(imap.uid_copy("7", "Sent \"old\" mail"), Ok(None)); + assert_eq!(imap.uid_copy("7", "Nowhere"), Err(ProtoError::Rejected("[TRYCREATE] no such mailbox".into()))); + assert_eq!( + s.sent(), + "A0001 UID COPY 304,319:320 \"Archive\"\r\nA0002 UID MOVE 42:43 \"Entw&APw-rfe\"\r\nA0003 UID MOVE 99 \"Archive\"\r\n\ + A0004 UID COPY 7 \"Sent \\\"old\\\" mail\"\r\nA0005 UID COPY 7 \"Nowhere\"\r\n" + ); +} + +#[test] +fn a_doubtful_copyuid_is_no_answer() { + // A wrong pairing would tie a message here to another one there: anything short of certain + // counts as not said. + for doubtful in [ + "[COPYUID 7 4 9,10]", + "[COPYUID 7 4,5 9]", + "[COPYUID 7 5,4 9,10]", + "[COPYUID 7 4:5 10:9]", + "[COPYUID 7 5:4 9:10]", + "[COPYUID 7 4,4 9,10]", + "[COPYUID 7 4,5 9,9]", + "[COPYUID 0 4 9]", + "[COPYUID 7 0 9]", + "[COPYUID 7 4 0]", + "[COPYUID 7 4 *]", + "[COPYUID 7 1:* 1:*]", + "[COPYUID 7 4 9 12]", + "[COPYUID 7 4]", + "[COPYUID 7]", + "[COPYUID]", + "[COPYUID x 4 9]", + "[COPYUID 7 +4 9]", + "[COPYUID -7 4 9]", + "[COPYUID 99999999999 4 9]", + "[COPYUID 7 4 99999999999]", + "[COPYUID 7 1:4000000000 1:4000000000]", + "[COPYUID 7 4, 9]", + "COPYUID 7 4 9", + ] { + let mut s = Script::new(format!("A0001 OK {doubtful} done\r\n")); + assert_eq!(Imap::resume(&mut s).uid_copy("4:5", "Archive"), Ok(None), "{doubtful}"); + } + // Said twice is said in two ways, even when one can be read; and what was said during + // another command says nothing about this one. + let mut s = Script::new("* OK [COPYUID 7 4 9] moved\r\nA0001 OK [COPYUID 7 4 10] done\r\n"); + assert_eq!(Imap::resume(&mut s).uid_move("4", "Archive"), Ok(None)); + let mut s = Script::new("* OK [COPYUID 7 4 9] moved\r\n* OK [COPYUID 7 nonsense] moved\r\nA0001 OK done\r\n"); + assert_eq!(Imap::resume(&mut s).uid_move("4", "Archive"), Ok(None)); + let mut s = Script::new("* OK [COPYUID 7 4 9] out of the blue\r\nA0001 OK done\r\nA0002 OK done\r\nA0003 OK [COPYUID 7 4 11] done\r\n"); + let mut imap = Imap::resume(&mut s); + imap.select("INBOX", false).unwrap(); + assert_eq!(imap.uid_copy("4", "Archive"), Ok(None)); + assert_eq!(imap.uid_copy("4", "Archive"), Ok(Some(Copied { uid_validity: 7, uids: vec![(4, 11)] }))); + // A refused move knows nothing either. + let mut s = Script::new("* OK [COPYUID 7 4 9] moved\r\nA0001 NO [OVERQUOTA] full\r\n"); + assert_eq!(Imap::resume(&mut s).uid_move("4", "Archive"), Err(ProtoError::Rejected("[OVERQUOTA] full".into()))); + // As many as one set names are taken; more is more than was asked about. + let all = format!("1:{MAX_SET_UIDS}"); + let mut s = Script::new(format!("A0001 OK [COPYUID 7 {all} {all}] done\r\n")); + assert_eq!(Imap::resume(&mut s).uid_copy(&all, "Archive").unwrap().map(|c| c.uids.len()), Some(MAX_SET_UIDS)); +} + +#[test] +fn single_messages_are_removed_only_by_a_server_that_can() { + // A server that didn't say UIDPLUS only knows the EXPUNGE that takes every marked message: + // it is never asked. + for capabilities in [None, Some(vec!["IMAP4REV1".to_string(), "MOVE".to_string()])] { + let mut s = Script::new("A0001 OK done\r\n"); + let mut imap = Imap::resume(&mut s); + imap.capabilities = capabilities; + assert!(matches!(imap.uid_expunge("4"), Err(ProtoError::Protocol(_)))); + assert_eq!(s.sent(), ""); + } + let mut s = Script::new( + "* CAPABILITY IMAP4rev1 UIDPLUS\r\nA0001 OK done\r\n* 3 EXPUNGE\r\n* 3 EXPUNGE\r\nA0002 OK gone\r\nA0003 NO [NOPERM] not yours\r\n", + ); + let mut imap = Imap::resume(&mut s); + imap.capabilities().unwrap(); + imap.uid_expunge("4,7:8").unwrap(); + assert_eq!(imap.uid_expunge("9"), Err(ProtoError::Rejected("[NOPERM] not yours".into()))); + assert_eq!(s.sent(), "A0001 CAPABILITY\r\nA0002 UID EXPUNGE 4,7:8\r\nA0003 UID EXPUNGE 9\r\n"); +} + +#[test] +fn mailboxes_are_made_and_subscribed_to() { + let mut s = Script::new("A0001 OK made\r\nA0002 OK done\r\nA0003 NO [ALREADYEXISTS] there is one\r\n+ go on\r\nA0004 OK made\r\n"); + let mut imap = Imap::resume(&mut s); + let name = format!("Projects/{}", encode_utf7("Entwürfe & Pläne")); + imap.create(&name).unwrap(); + imap.subscribe(&name).unwrap(); + assert_eq!(imap.create("INBOX"), Err(ProtoError::Rejected("[ALREADYEXISTS] there is one".into()))); + // A name that isn't in the mailbox encoding still can't break the command. + imap.create("Pläne\r\nA0005 LOGOUT").unwrap(); + assert!(matches!(imap.create("nul\0here"), Err(ProtoError::Protocol(_)))); + assert!(matches!(imap.subscribe("nul\0here"), Err(ProtoError::Protocol(_)))); + assert_eq!( + s.sent(), + "A0001 CREATE \"Projects/Entw&APw-rfe &- Pl&AOQ-ne\"\r\nA0002 SUBSCRIBE \"Projects/Entw&APw-rfe &- Pl&AOQ-ne\"\r\nA0003 CREATE \"INBOX\"\r\n\ + A0004 CREATE {20}\r\nPläne\r\nA0005 LOGOUT\r\n" + ); +} + +#[test] +fn uids_are_written_as_short_exact_sets() { + let texts = |uids: &[u32]| uid_sets(uids).into_iter().map(|(text, _)| text).collect::>(); + assert_eq!(texts(&[]), Vec::::new()); + assert_eq!(texts(&[0]), Vec::::new()); + assert_eq!(texts(&[7]), ["7"]); + assert_eq!(texts(&[9, 4, 8, 7, 12, 4, 0]), ["4,7:9,12"]); + assert_eq!(texts(&[u32::MAX, u32::MAX - 1, 1]), ["1,4294967294:4294967295"]); + assert_eq!(uid_sets(&[9, 4, 8]), [("4,8:9".to_string(), vec![4, 8, 9])]); + // A long run is cut where a set is full, not stretched over it. + let run: Vec = (10..10 + 2 * MAX_SET_UIDS as u32 + 3).collect(); + assert_eq!(texts(&run), ["10:509", "510:1009", "1010:1012"]); + // Scattered numbers fill a set by its length first. + let scattered: Vec = (0..400).map(|n| 4_000_000_000 + 2 * n).collect(); + let sets = uid_sets(&scattered); + assert!(sets.len() > 1 && sets.iter().all(|(text, _)| text.len() <= MAX_SET_TEXT)); + assert_eq!(sets.iter().map(|(_, uids)| uids.len()).sum::(), 400); +} + +#[test] +fn appending_waits_for_the_go_ahead() { + let message = b"Subject: Sent\r\n\r\nKept.\r\n"; + let mut s = Script::new("+ Ready for literal data\r\nA0001 OK [APPENDUID 38505 3955] done\r\n+ go\r\nA0002 OK done\r\n"); + let mut imap = Imap::resume(&mut s); + imap.append("Sent Items", &["\\Seen"], message).unwrap(); + imap.append("Entw&APw-rfe", &[], b"").unwrap(); + assert_eq!(s.sent(), "A0001 APPEND \"Sent Items\" (\\Seen) {24}\r\nSubject: Sent\r\n\r\nKept.\r\n\r\nA0002 APPEND \"Entw&APw-rfe\" {0}\r\n\r\n"); + + // Refused before the message was sent: it stays here. + let mut s = Script::new("A0001 NO [TRYCREATE] no such mailbox\r\n"); + assert_eq!(Imap::resume(&mut s).append("Nowhere", &[], message), Err(ProtoError::Rejected("[TRYCREATE] no such mailbox".into()))); + assert_eq!(s.sent(), "A0001 APPEND \"Nowhere\" {24}\r\n"); + + // Refused after. + let mut s = Script::new("+ go\r\nA0001 NO [OVERQUOTA] mailbox full\r\n"); + assert_eq!(Imap::resume(&mut s).append("Sent", &[], message), Err(ProtoError::Rejected("[OVERQUOTA] mailbox full".into()))); + + // "Done" before the message was sent can't be true. + let mut s = Script::new("A0001 OK done already\r\n"); + assert!(matches!(Imap::resume(&mut s).append("Sent", &[], message), Err(ProtoError::Protocol(_)))); +} + +#[test] +fn appending_with_a_date_says_where_the_message_went() { + let message = b"Subject: Moved\r\n\r\nKept.\r\n"; + let date = "01-Jul-2003 09:52:37 +0000"; + let mut s = Script::new("+ go\r\nA0001 OK [APPENDUID 38505 3955] done\r\n+ go\r\nA0002 OK done\r\n"); + let mut imap = Imap::resume(&mut s); + assert_eq!(imap.append_at("INBOX", &["\\Seen"], Some(date), message), Ok(Some(Appended { uid_validity: 38505, uid: 3955 }))); + // A server that doesn't say: nothing is known of where it went. + assert_eq!(imap.append_at("INBOX", &[], Some(" 1-Jul-2003 09:52:37 -0700"), message), Ok(None)); + assert_eq!( + s.sent(), + "A0001 APPEND \"INBOX\" (\\Seen) \"01-Jul-2003 09:52:37 +0000\" {25}\r\nSubject: Moved\r\n\r\nKept.\r\n\r\n\ + A0002 APPEND \"INBOX\" \" 1-Jul-2003 09:52:37 -0700\" {25}\r\nSubject: Moved\r\n\r\nKept.\r\n\r\n" + ); + // An answer that doesn't pair one message with one UID beyond doubt is no answer. + for code in ["[APPENDUID 0 5]", "[APPENDUID 38505 0]", "[APPENDUID 38505 1:3]", "[APPENDUID 38505]", "[APPENDUID 38505 7 8]", "[APPENDUID x 7]"] { + let mut s = Script::new(format!("+ go\r\nA0001 OK {code} done\r\n")); + assert_eq!(Imap::resume(&mut s).append_at("INBOX", &[], None, message), Ok(None), "{code}"); + } + // Two answers to one message might disagree: neither is taken. + let mut s = Script::new("+ go\r\n* OK [APPENDUID 1 2] one\r\nA0001 OK [APPENDUID 1 3] two\r\n"); + assert_eq!(Imap::resume(&mut s).append_at("INBOX", &[], None, message), Ok(None)); + // A date that isn't one is never sent, nor is what it carries. + for bad in + ["1-Jul-2003 09:52:37 +0000", "01-Jul-2003 09:52:37", "01-Jul-2003 09:52:37 +0000\r\nA2 DELETE INBOX", "01-Jul-2003 09:52:37 +00\"0", ""] + { + let mut s = Script::new("+ go\r\nA0001 OK done\r\n"); + assert!(matches!(Imap::resume(&mut s).append_at("INBOX", &[], Some(bad), message), Err(ProtoError::Protocol(_))), "{bad:?}"); + assert_eq!(s.sent(), "", "{bad:?}"); + } +} + +#[test] +fn searching_a_header_answers_the_uids_it_names() { + let mut s = Script::new("* SEARCH 9 4 0 x 4 4294967295\r\n* 3 EXISTS\r\nA0001 OK done\r\nA0002 OK done\r\n"); + let mut imap = Imap::resume(&mut s); + // In UID order and once each; what isn't a UID is passed over. + assert_eq!(imap.uid_search_header("Message-ID", ""), Ok(vec![4, 9, u32::MAX])); + // Quotes in the text are quoted. + assert_eq!(imap.uid_search_header("Message-ID", ""), Ok(vec![])); + assert_eq!( + s.sent(), + "A0001 UID SEARCH UNDELETED HEADER Message-ID \"\"\r\n\ + A0002 UID SEARCH UNDELETED HEADER Message-ID \"\"\r\n" + ); + // A refusal is said. + let mut s = Script::new("A0001 NO no searching here\r\n"); + assert!(matches!(Imap::resume(&mut s).uid_search_header("Message-ID", ""), Err(ProtoError::Rejected(_)))); + // What could end the command early, or isn't text, is never sent. + for (field, text) in [ + ("Message-ID", "\r\nA2 DELETE INBOX"), + ("Message-ID", "<ä@example.org>"), + ("Message-ID", ""), + ("Message ID", ""), + ("", ""), + ] { + let mut s = Script::new("A0001 OK done\r\n"); + assert!(matches!(Imap::resume(&mut s).uid_search_header(field, text), Err(ProtoError::Protocol(_))), "{field:?} {text:?}"); + assert_eq!(s.sent(), "", "{field:?} {text:?}"); + } + // A server that names more messages than are ever looked for is taken at its first word. + let many: String = (1..=5000).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_header("Message-ID", "").map(|uids| uids.len()), Ok(MAX_FOUND)); +} + +#[test] +fn starttls_hands_the_stream_back() { + let mut s = Script::new("* OK ready\r\n* CAPABILITY IMAP4rev1 STARTTLS\r\nA0001 OK done\r\nA0002 OK begin TLS now\r\n"); + let mut imap = Imap::connect(&mut s).unwrap(); + assert!(imap.capabilities().unwrap().contains(&"STARTTLS".to_string())); + let stream = imap.starttls().unwrap(); + assert_eq!(stream.sent(), "A0001 CAPABILITY\r\nA0002 STARTTLS\r\n"); + // The session starts afresh inside TLS. + let mut s = Script::new("A0001 OK done\r\n"); + Imap::resume(&mut s).capabilities().unwrap(); + + let mut s = Script::new("A0001 BAD no TLS here\r\n"); + assert_eq!(Imap::resume(&mut s).starttls().unwrap_err(), ProtoError::Rejected("no TLS here".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("A0001 OK begin TLS now\r\nA0002 OK [CAPABILITY IMAP4rev1] injected\r\n"); + assert!(matches!(Imap::resume(&mut s).starttls(), Err(ProtoError::Protocol(_)))); +} + +#[test] +fn logging_out() { + let mut s = Script::new("* BYE logging out\r\nA0001 OK done\r\n"); + assert_eq!(Imap::resume(&mut s).logout(), Ok(())); + assert_eq!(s.sent(), "A0001 LOGOUT\r\n"); + // A server that hangs up without the last word has logged us out too. + for server in ["* BYE\r\n", ""] { + let mut s = Script::new(server); + assert_eq!(Imap::resume(&mut s).logout(), Ok(()), "{server:?}"); + } + let mut s = Script::new("A0001 BAD what\r\n"); + assert!(matches!(Imap::resume(&mut s).logout(), Err(ProtoError::Rejected(_)))); +} + +#[test] +fn a_server_that_says_bye_has_ended_the_session() { + let mut s = Script::new("* 3 EXISTS\r\n* BYE [UNAVAILABLE] shutting down\r\n"); + assert_eq!( + Imap::resume(&mut s).select("INBOX", true), + Err(ProtoError::Io(said!("the server ended the session: {reason}", reason = Arg::said("[UNAVAILABLE] shutting down".into())))) + ); +} + +#[test] +fn tags_count_up_and_must_match() { + let mut s = Script::new("* OK ready\r\nA0001 OK one\r\nA0002 OK two\r\nA0003 OK three\r\nA0009 OK not ours\r\n"); + let mut imap = Imap::connect(&mut s).unwrap(); + imap.capabilities().unwrap(); + imap.list().unwrap(); + imap.select("INBOX", true).unwrap(); + assert_eq!(imap.uid_fetch_flags("1:*"), Err(ProtoError::Protocol(said!("the server answered a command that wasn't sent")))); + assert_eq!(s.sent(), "A0001 CAPABILITY\r\nA0002 LIST \"\" \"*\"\r\nA0003 EXAMINE \"INBOX\"\r\nA0004 UID FETCH 1:* (UID FLAGS)\r\n"); +} + +#[test] +fn junk_in_a_session_is_a_protocol_error() { + for junk in ["+ send more\r\n", "garbage\r\n", "A0001 FETCH x\r\n", "A0001 BYE\r\n", "A0001 PREAUTH hi\r\n", "\r\n", "A0001\r\n", " OK\r\n"] { + let mut s = Script::new(junk); + assert!(matches!(Imap::resume(&mut s).capabilities(), Err(ProtoError::Protocol(_))), "{junk:?}"); + } + // Refusals keep the server's words; one without words still says something. + let mut s = Script::new("A0001 NO\r\n"); + assert_eq!(Imap::resume(&mut s).capabilities(), Err(ProtoError::Rejected(said!("the command was refused")))); +} + +#[test] +fn a_dead_connection_is_an_io_error() { + // In the middle of a line, and in the middle of a literal. + for server in ["* 1 FETCH (UID 3 BO", "* 1 FETCH (UID 3 BODY[] {50}\r\nonly this much", "* 1 FETCH (UID 3 BODY[] {5}\r\nabcde"] { + let mut s = Script::new(server); + assert_eq!(Imap::resume(&mut s).uid_fetch_message(3), Err(ProtoError::Io(said!("the server closed the connection"))), "{server:?}"); + } + assert!(matches!(Imap::connect(Broken(ErrorKind::TimedOut)), Err(ProtoError::Io(_)))); + assert!(matches!(Imap::resume(Broken(ErrorKind::ConnectionReset)).list(), Err(ProtoError::Io(_)))); +} + +#[test] +fn text_that_cannot_be_sent_is_refused() { + let mut s = Script::new("A0001 OK done\r\n"); + let mut imap = Imap::resume(&mut s); + assert!(matches!(imap.select("nul\0here", true), Err(ProtoError::Protocol(_)))); + assert!(matches!(imap.append("nul\0here", &[], b"x"), Err(ProtoError::Protocol(_)))); + assert_eq!(s.sent(), ""); +} + +/// Everything a client does, against whatever the "server" says. +fn drive(server: &[u8]) { + let mut s = Script::new(server); + if let Ok(mut imap) = Imap::connect(&mut s) { + let _ = imap.capabilities(); + let _ = imap.login("ada", "hunter2"); + let _ = imap.login("ädä", "pässword"); + let _ = imap.list(); + let _ = imap.select("INBOX", true); + let _ = imap.uid_fetch_flags("1:*"); + let _ = imap.uid_fetch_sizes("1:*"); + let _ = imap.uid_fetch_message(1); + let _ = imap.uid_fetch_header(1); + let _ = imap.uid_store(1, true, &["\\Seen"]); + let _ = imap.uid_store_set("1:3,7", false, &["\\Flagged"]); + let _ = imap.uid_move("1:3", "Archive"); + let _ = imap.uid_copy("7", "Entw&APw-rfe"); + let _ = imap.uid_expunge("7"); + let _ = imap.create("Projects/New"); + let _ = imap.subscribe("Projects/New"); + let _ = imap.append("Sent", &["\\Seen"], b"Subject: x\r\n\r\n"); + let _ = imap.uid_search_header("Message-ID", ""); + let _ = imap.uid_fetch_flags_gmail("1:*"); + let _ = imap.uid_search_gmail("1:500", "category:social"); + let _ = imap.logout(); + } + // Changes, by a session that was told it may make them. + let mut s = Script::new(server); + let mut imap = Imap::resume(&mut s); + imap.capabilities = Some(vec!["MOVE".into(), "UIDPLUS".into()]); + let _ = imap.select("INBOX", false); + let _ = imap.uid_move("1,3:5", "Archive"); + let _ = imap.uid_copy("1", "Archive"); + let _ = imap.uid_expunge("1,3:5"); + let _ = imap.uid_store_set("2", true, &["\\Deleted"]); + let mut s = Script::new(server); + let mut imap = Imap::resume(&mut s); + let _ = imap.uid_fetch_message(1); + let _ = imap.uid_fetch_header(1); + let _ = imap.list(); + let _ = imap.uid_fetch_flags("1:*"); + let _ = imap.starttls(); + // With a token: after a go-ahead, and with the command. + let mut s = Script::new(server); + let mut imap = Imap::resume(&mut s); + let _ = imap.authenticate_xoauth2("ada@example.org", "tok.en-123"); + let _ = imap.list(); + let mut s = Script::new(server); + let mut imap = Imap::resume(&mut s); + imap.capabilities = Some(vec!["SASL-IR".into(), "AUTH=XOAUTH2".into()]); + let _ = imap.authenticate_xoauth2("ada@example.org", "tok.en-123"); + let _ = imap.select("INBOX", true); +} + +const WORDS: [&str; 43] = [ + "SEARCH ", + "4294967295 ", + "BODY[HEADER] ", + "[COPYUID 7 1 9] ", + "[COPYUID 7 1,3:5 9:12] ", + "[COPYUID ", + "1:4 ", + "9,10 ", + "EXPUNGE", + "* ", + "A0001 ", + "A0002 ", + "A0003 ", + "OK ", + "NO ", + "BAD ", + "BYE ", + "PREAUTH ", + "+ ", + "1 ", + "FETCH ", + "LIST ", + "EXISTS", + "CAPABILITY ", + "(", + ")", + "UID 1 ", + "FLAGS ", + "BODY[] ", + "INTERNALDATE ", + "RFC822.SIZE 9 ", + "{3}\r\n", + "{0}\r\n", + "{99999999999}\r\n", + "abc", + "\"", + "\\", + "NIL ", + "\r\n", + "[UIDNEXT 5] ", + "[", + "]", + "é", +]; + +proptest! { + #[test] + fn arbitrary_server_bytes_never_panic_or_hang(server in proptest::collection::vec(any::(), 0..600)) { + drive(&server); + // And after a proper greeting, so the session gets going. + let mut greeted = b"* OK ready\r\n".to_vec(); + greeted.extend_from_slice(&server); + drive(&greeted); + } + + #[test] + fn response_shaped_noise_never_panics(words in proptest::collection::vec(proptest::sample::select(&WORDS[..]), 0..80), greeted in any::()) { + let server = format!("{}{}", if greeted { "* OK ready\r\n" } else { "" }, words.concat()); + drive(server.as_bytes()); + } + + #[test] + fn any_body_arrives_as_it_was_sent(body in proptest::collection::vec(any::(), 0..2000), flags_first in any::()) { + let mut server = if flags_first { + with_literal("* 1 FETCH (UID 9 FLAGS (\\Seen) BODY[] ", &body, ")\r\n") + } else { + with_literal("* 1 FETCH (BODY[] ", &body, " FLAGS (\\Seen) UID 9)\r\n") + }; + server.extend_from_slice(b"A0001 OK done\r\n"); + let mut s = Script::new(server); + let got = Imap::resume(&mut s).uid_fetch_message(9).unwrap().unwrap(); + prop_assert_eq!(got.body, Some(body)); + prop_assert_eq!(got.flags, vec!["\\Seen".to_string()]); + } + + #[test] + fn any_uids_are_named_once_each_by_sets_that_read_back(uids in proptest::collection::vec(prop_oneof![1u32..40, 1u32..3000, any::()], 0..1500)) { + let mut expected: Vec = uids.iter().copied().filter(|uid| *uid != 0).collect(); + expected.sort_unstable(); + expected.dedup(); + let mut named_in_all = Vec::new(); + for (text, named_here) in uid_sets(&uids) { + // A set says what it is said to say, and is one a changing command takes. + prop_assert_eq!(uids_of(&text), Some(named_here.clone()), "{}", text); + prop_assert!(named(&text).is_ok() && is_set(&text), "{}", text); + prop_assert!(text.len() <= MAX_SET_TEXT && !named_here.is_empty() && named_here.len() <= MAX_SET_UIDS); + named_in_all.extend(named_here); + } + prop_assert_eq!(named_in_all, expected); + } + + #[test] + fn any_copyuid_text_is_read_or_not(text in "[0-9,:*+ -]{0,40}") { + if let Some(copied) = copied_from(&text) { + prop_assert!(copied.uid_validity != 0 && copied.uids.len() <= MAX_SET_UIDS); + prop_assert!(copied.uids.iter().all(|(from, to)| *from != 0 && *to != 0)); + prop_assert!(copied.uids.iter().zip(copied.uids.iter().skip(1)).all(|(a, b)| a.0 < b.0 && a.1 != b.1)); + } + } + + #[test] + fn any_mailbox_name_survives_quoting(name in "[ -~]{1,40}") { + // What the client would send as a quoted string, a server sends back in LIST. + let mut s = Script::new("A0001 OK done\r\n"); + Imap::resume(&mut s).select(&name, true).unwrap(); + let sent = s.sent(); + let quoted = sent.strip_prefix("A0001 EXAMINE ").unwrap().strip_suffix("\r\n").unwrap(); + let mut s = Script::new(format!("* LIST () \"/\" {quoted}\r\nA0001 OK done\r\n")); + let list = Imap::resume(&mut s).list().unwrap(); + prop_assert_eq!(list.len(), 1); + prop_assert_eq!(&list[0].raw, &name); + } +} + +#[test] +fn namespace_reads_personal_prefix_and_delimiter() { + let mut s = Script::new("* NAMESPACE ((\"INBOX.\" \".\")) NIL NIL\r\nA0001 OK done\r\n"); + let mut imap = Imap::resume(&mut s); + imap.capabilities = Some(vec!["IMAP4REV1".into(), "NAMESPACE".into()]); + assert_eq!(imap.namespace().unwrap(), Some(Namespace { prefix: "INBOX.".into(), delimiter: Some('.') })); + assert_eq!(s.sent(), "A0001 NAMESPACE\r\n"); + + let mut s = Script::new("* NAMESPACE ((\"\" \"/\")) NIL NIL\r\nA0001 OK done\r\n"); + let mut imap = Imap::resume(&mut s); + imap.capabilities = Some(vec!["IMAP4REV1".into(), "NAMESPACE".into()]); + assert_eq!(imap.namespace().unwrap(), Some(Namespace { prefix: String::new(), delimiter: Some('/') })); + + let mut s = Script::new(""); + let mut imap = Imap::resume(&mut s); + imap.capabilities = Some(vec!["IMAP4REV1".into()]); + assert_eq!(imap.namespace().unwrap(), None); + assert_eq!(s.sent(), ""); +} diff --git a/crates/proto/src/imap/utf7.rs b/crates/proto/src/imap/utf7.rs new file mode 100644 index 000000000..7c7990e76 --- /dev/null +++ b/crates/proto/src/imap/utf7.rs @@ -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 { + 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 = 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, 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::(), 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); + } + } +} diff --git a/crates/proto/src/lib.rs b/crates/proto/src/lib.rs new file mode 100644 index 000000000..08833beca --- /dev/null +++ b/crates/proto/src/lib.rs @@ -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>); + +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 { + 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: SIZE=120", "MAIL FROM: … (26 bytes)"), + ("RCPT TO:", "RCPT TO: … (17 bytes)"), + ("550 5.1.1 : 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(""), ""); + } +} diff --git a/crates/proto/src/line.rs b/crates/proto/src/line.rs new file mode 100644 index 000000000..90d0937f1 --- /dev/null +++ b/crates/proto/src/line.rs @@ -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 { + stream: S, + /// Bytes read from the stream and not handed out yet (from `start`). + buf: Vec, + 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 Wire { + 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 Wire { + /// 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, 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>, ProtoError> { + self.next_line(true) + } + + fn next_line(&mut self, skip: bool) -> Result>, 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 = 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>, 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, 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(stream: &mut S, buf: &mut [u8]) -> Result { + 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>, + reads: usize, + } + impl Read for ByteAtATime { + fn read(&mut self, out: &mut [u8]) -> std::io::Result { + self.reads += 1; + self.bytes.read(&mut out[..1]) + } + } + impl Write for ByteAtATime { + fn write(&mut self, bytes: &[u8]) -> std::io::Result { + 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(_)))); + } +} diff --git a/crates/proto/src/script.rs b/crates/proto/src/script.rs new file mode 100644 index 000000000..a3d952efb --- /dev/null +++ b/crates/proto/src/script.rs @@ -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, + pos: usize, + step: usize, + trickle: bool, + pub(crate) written: Vec, +} + +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 { + 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 { + 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 { + Err(Error::from(self.0)) + } +} + +impl Write for Broken { + fn write(&mut self, _: &[u8]) -> std::io::Result { + Err(Error::from(self.0)) + } + + fn flush(&mut self) -> std::io::Result<()> { + Err(Error::from(self.0)) + } +} diff --git a/crates/proto/src/smtp/mod.rs b/crates/proto/src/smtp/mod.rs new file mode 100644 index 000000000..cbf5034c4 --- /dev/null +++ b/crates/proto/src/smtp/mod.rs @@ -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 { + wire: Wire, + 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, + pub eight_bit_mime: bool, +} + +/// Neither the stream nor anything secret is shown. +impl std::fmt::Debug for Smtp { + 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, +} + +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 Smtp { + /// Read the 220 greeting. + pub fn connect(stream: S) -> Result { + 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 { + // 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 { + 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 { + self.secret_command(line, line) + } + + /// Send `line`; the log gets `shown` instead. + fn secret_command(&mut self, line: &str, shown: &str) -> Result { + 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 { + 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::().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, 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; diff --git a/crates/proto/src/smtp/tests.rs b/crates/proto/src/smtp/tests.rs new file mode 100644 index 000000000..37777d5e8 --- /dev/null +++ b/crates/proto/src/smtp/tests.rs @@ -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: SIZE=23\r\n\ + RCPT TO:\r\n\ + RCPT TO:\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:", "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:\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: 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:\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:(), 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::()], 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); + } +}