Skip to main content

hypermail/
mbox.rs

1use crate::error::{HypermailError, Result};
2use std::io::{BufRead, BufReader, Read};
3
4/// Maximum size for a single email message (100 MB).
5///
6/// This prevents denial-of-service attacks via extremely large messages
7/// that could exhaust memory. Legitimate emails are typically < 50 MB
8/// even with large attachments.
9const MAX_MESSAGE_SIZE: usize = 100 * 1024 * 1024;
10
11/// Maximum line length for email headers or body lines (10 MB).
12///
13/// RFC 2822 recommends lines < 998 characters, but we allow much larger
14/// for compatibility with malformed messages and large MIME parts.
15/// This prevents memory exhaustion from pathological single-line inputs.
16const MAX_LINE_SIZE: usize = 10 * 1024 * 1024;
17
18/// Supported mbox format variants for "From " line escaping strategies.
19#[derive(Debug, Clone, PartialEq)]
20pub enum MboxFormat {
21    MboxO,
22    MboxRd,
23    MboxCl,
24    MboxCl2,
25}
26
27/// A single raw email message split into envelope line, headers, and body bytes.
28#[derive(Debug, Clone)]
29pub struct RawMessage {
30    pub from_line: String,
31    pub headers: Vec<u8>,
32    pub body: Vec<u8>,
33}
34
35/// Streaming iterator that splits an mbox file into individual messages.
36///
37/// # Security
38///
39/// Enforces per-message and per-line size limits to prevent memory exhaustion
40/// from malicious or malformed input.
41/// Stops after any read or size-limit error; partial messages are never returned.
42pub struct MboxReader<R: Read> {
43    reader: BufReader<R>,
44    format: MboxFormat,
45    line_num: usize,
46    buffer: Vec<u8>,
47    eof: bool,
48    max_message_size: usize,
49}
50
51impl<R: Read> MboxReader<R> {
52    /// Creates a new mbox reader with the given format variant.
53    pub fn new(reader: R, format: MboxFormat) -> Self {
54        MboxReader {
55            reader: BufReader::new(reader),
56            format,
57            line_num: 0,
58            buffer: Vec::new(),
59            eof: false,
60            max_message_size: MAX_MESSAGE_SIZE,
61        }
62    }
63
64    /// Overrides the default maximum message size limit.
65    pub fn with_max_message_size(mut self, size: usize) -> Self {
66        self.max_message_size = size;
67        self
68    }
69
70    fn is_from_line(line: &[u8]) -> bool {
71        line.starts_with(b"From ") && line.len() > 5
72    }
73
74    fn unescape_mboxrd(line: &[u8]) -> Vec<u8> {
75        // MboxRd: strip exactly one leading '>' from lines that start with
76        // one or more '>' followed by "From ". This correctly handles
77        // multi-level escaping: ">>From " → ">From ", ">>>From " → ">>From ".
78        if line.len() > 1 && line[0] == b'>' {
79            // Count leading '>' characters
80            let gt_count = line.iter().take_while(|&&b| b == b'>').count();
81            // Check if after the '>' sequence we have "From "
82            if line[gt_count..].starts_with(b"From ") {
83                return line[1..].to_vec();
84            }
85        }
86        line.to_vec()
87    }
88}
89
90impl<R: Read> Iterator for MboxReader<R> {
91    type Item = Result<RawMessage>;
92
93    fn next(&mut self) -> Option<Self::Item> {
94        if self.eof {
95            return None;
96        }
97
98        loop {
99            let mut line = Vec::new();
100            self.line_num += 1;
101
102            match self.reader.by_ref().take(MAX_LINE_SIZE as u64 + 1).read_until(b'\n', &mut line) {
103                Ok(0) => {
104                    self.eof = true;
105                    if self.buffer.is_empty() {
106                        return None;
107                    }
108                    break;
109                },
110                Ok(_) => {},
111                Err(e) => {
112                    self.eof = true;
113                    self.buffer.clear();
114                    return Some(Err(HypermailError::MboxParse {
115                        line: self.line_num,
116                        message: format!("read error: {e}"),
117                    }));
118                },
119            }
120
121            // Security: Check line size to prevent memory exhaustion
122            // from pathological inputs with extremely long lines
123            if line.len() > MAX_LINE_SIZE {
124                self.eof = true;
125                self.buffer.clear();
126                return Some(Err(HypermailError::MboxParse {
127                    line: self.line_num,
128                    message: format!(
129                        "line exceeds maximum size ({} bytes > {} bytes)",
130                        line.len(),
131                        MAX_LINE_SIZE
132                    ),
133                }));
134            }
135
136            if line.last() == Some(&b'\n') {
137                line.pop();
138                if line.last() == Some(&b'\r') {
139                    line.pop();
140                }
141            }
142
143            if (self.buffer.is_empty() || Self::is_from_line(&line))
144                && line.len() + 1 > self.max_message_size
145            {
146                self.eof = true;
147                self.buffer.clear();
148                return Some(Err(HypermailError::MboxParse {
149                    line: self.line_num,
150                    message: "envelope exceeds maximum message size".to_string(),
151                }));
152            }
153
154            if self.buffer.is_empty() {
155                if Self::is_from_line(&line) {
156                    self.buffer = line;
157                    self.buffer.push(b'\n');
158                    continue;
159                }
160                self.buffer = line;
161                self.buffer.push(b'\n');
162                continue;
163            }
164
165            if Self::is_from_line(&line) {
166                let raw = self.buffer.split_off(0);
167                self.buffer = line;
168                self.buffer.push(b'\n');
169                return Some(Ok(parse_raw_message(&raw)));
170            }
171
172            // Security: Check total message size before appending
173            // Prevents denial-of-service via extremely large messages
174            let new_size = self.buffer.len() + line.len() + 1;
175            if new_size > self.max_message_size {
176                self.eof = true;
177                self.buffer.clear();
178                return Some(Err(HypermailError::MboxParse {
179                    line: self.line_num,
180                    message: format!(
181                        "message exceeds maximum size ({} bytes > {} bytes)",
182                        new_size, self.max_message_size
183                    ),
184                }));
185            }
186
187            if self.format == MboxFormat::MboxRd {
188                let unescaped = Self::unescape_mboxrd(&line);
189                self.buffer.extend_from_slice(&unescaped);
190            } else {
191                self.buffer.extend_from_slice(&line);
192            }
193            self.buffer.push(b'\n');
194        }
195
196        if self.buffer.is_empty() {
197            return None;
198        }
199        let raw = std::mem::take(&mut self.buffer);
200        Some(Ok(parse_raw_message(&raw)))
201    }
202}
203
204fn parse_raw_message(data: &[u8]) -> RawMessage {
205    let from_end = data.iter().position(|&b| b == b'\n').unwrap_or(data.len());
206    let from_line = String::from_utf8_lossy(&data[..from_end]).trim_end().to_string();
207
208    let rest = if from_end + 1 < data.len() {
209        &data[from_end + 1..]
210    } else {
211        &[]
212    };
213
214    if let Some(body) = rest.strip_prefix(b"\n") {
215        return RawMessage { from_line, headers: Vec::new(), body: body.to_vec() };
216    }
217
218    let sep = rest
219        .windows(2)
220        .position(|w| w == b"\n\n")
221        .or_else(|| rest.windows(4).position(|w| w == b"\r\n\r\n").map(|p| p + 2));
222
223    if let Some(headers_end) = sep {
224        let header_bytes = rest[..headers_end].to_vec();
225        let body_bytes = if headers_end + 2 < rest.len() {
226            let skip = if rest[headers_end..].starts_with(b"\r\n") {
227                4
228            } else {
229                2
230            };
231            if headers_end + skip < rest.len() {
232                rest[headers_end + skip..].to_vec()
233            } else {
234                Vec::new()
235            }
236        } else {
237            Vec::new()
238        };
239        RawMessage { from_line, headers: header_bytes, body: body_bytes }
240    } else {
241        RawMessage { from_line, headers: rest.to_vec(), body: Vec::new() }
242    }
243}
244
245#[cfg(test)]
246mod tests {
247    use super::*;
248    use std::io::Cursor;
249
250    #[test]
251    fn test_oversized_line_read_is_bounded() {
252        let data = vec![b'a'; MAX_LINE_SIZE * 2];
253        let mut reader = MboxReader::new(Cursor::new(data), MboxFormat::MboxO);
254        assert!(reader.next().unwrap().is_err());
255        assert!(reader.reader.get_ref().position() <= (MAX_LINE_SIZE + 8192) as u64);
256        assert!(reader.next().is_none());
257    }
258
259    #[test]
260    fn test_oversized_message_stops_without_returning_body_as_message() {
261        let data = b"From a\nSubject: first\n\nlong body\nremaining body\nFrom b\n\nok\n";
262        let mut reader =
263            MboxReader::new(Cursor::new(data), MboxFormat::MboxO).with_max_message_size(25);
264        assert!(reader.next().unwrap().is_err());
265        assert!(reader.next().is_none());
266    }
267
268    #[test]
269    fn test_envelope_alone_respects_message_limit() {
270        let mut reader = MboxReader::new(Cursor::new(b"From a long envelope\n"), MboxFormat::MboxO)
271            .with_max_message_size(5);
272        assert!(reader.next().unwrap().is_err());
273        assert!(reader.next().is_none());
274    }
275
276    fn create_mbox_data() -> Vec<u8> {
277        b"From alice@example.com Mon Jan 01 12:00:00 2024\n\
278          From: Alice <alice@example.com>\n\
279          Subject: First message\n\
280          Message-ID: <001@example.com>\n\
281          Date: Mon, 01 Jan 2024 12:00:00 +0000\n\
282          \n\
283          This is the first message body.\n\
284          \n\
285          From bob@example.com Mon Jan 01 13:00:00 2024\n\
286          From: Bob <bob@example.com>\n\
287          Subject: Re: First message\n\
288          Message-ID: <002@example.com>\n\
289          In-Reply-To: <001@example.com>\n\
290          Date: Mon, 01 Jan 2024 13:00:00 +0000\n\
291          \n\
292          This is a reply.\n\
293          \n\
294          From carol@example.com Mon Jan 01 14:00:00 2024\n\
295          From: Carol <carol@example.com>\n\
296          Subject: Another thread\n\
297          Message-ID: <003@example.com>\n\
298          Date: Mon, 01 Jan 2024 14:00:00 +0000\n\
299          \n\
300          A different conversation.\n"
301            .to_vec()
302    }
303
304    #[test]
305    fn test_parse_mbox_basic() {
306        let data = create_mbox_data();
307        let cursor = Cursor::new(data);
308        let reader = MboxReader::new(cursor, MboxFormat::MboxO);
309        let messages: Vec<Result<RawMessage>> = reader.collect();
310        assert_eq!(messages.len(), 3);
311
312        let msg0 = messages[0].as_ref().unwrap();
313        assert!(msg0.from_line.contains("alice@example.com"));
314
315        let headers = crate::headers::parse_headers(&msg0.headers);
316        assert_eq!(crate::headers::find_header(&headers, "Subject"), Some("First message"));
317    }
318
319    #[test]
320    fn test_from_line_parsing() {
321        assert!(MboxReader::<std::io::Empty>::is_from_line(b"From alice@example.com Mon Jan 01"));
322        assert!(!MboxReader::<std::io::Empty>::is_from_line(b"From: alice@example.com"));
323        assert!(!MboxReader::<std::io::Empty>::is_from_line(b""));
324    }
325
326    #[test]
327    fn test_empty_mbox() {
328        let cursor = Cursor::new(b"");
329        let reader = MboxReader::new(cursor, MboxFormat::MboxO);
330        let count = reader.count();
331        assert_eq!(count, 0);
332    }
333
334    #[test]
335    fn test_mbox_no_headers() {
336        let data = b"From alice@example.com\n\nJust a body\n".to_vec();
337        let cursor = Cursor::new(data);
338        let reader = MboxReader::new(cursor, MboxFormat::MboxO);
339        let messages: Vec<Result<RawMessage>> = reader.collect();
340        assert_eq!(messages.len(), 1);
341        assert!(messages[0].is_ok());
342        assert_eq!(messages[0].as_ref().unwrap().body, b"Just a body\n");
343    }
344
345    #[test]
346    fn test_multipart_message_with_from_in_body() {
347        let data = b"From alice@example.com\n\
348                     From: Alice <alice@example.com>\n\
349                     Subject: Test\n\
350                     \n\
351                     This line looks like\n\
352                     >From someone else\n\
353                     but shouldn't be split.\n"
354            .to_vec();
355        let cursor = Cursor::new(data);
356        let reader = MboxReader::new(cursor, MboxFormat::MboxRd);
357        let messages: Vec<Result<RawMessage>> = reader.collect();
358        assert_eq!(messages.len(), 1);
359        let msg = messages[0].as_ref().unwrap();
360        assert_eq!(msg.from_line, "From alice@example.com");
361        let body_str = std::str::from_utf8(&msg.body).unwrap();
362        assert!(body_str.contains("From someone else"));
363    }
364
365    #[test]
366    fn test_max_message_size_exceeded() {
367        let data = b"From alice@example.com\n\
368                     From: Alice <alice@example.com>\n\
369                     \n\
370                     This is a very long body line that exceeds our tiny limit.\n"
371            .to_vec();
372        let cursor = Cursor::new(data);
373        let reader = MboxReader::new(cursor, MboxFormat::MboxO).with_max_message_size(10);
374        let results: Vec<Result<RawMessage>> = reader.collect();
375        assert!(
376            results.iter().any(|r| r.is_err()),
377            "Should fail when message exceeds size limit"
378        );
379    }
380
381    #[test]
382    fn test_mboxrd_unescape() {
383        // MboxRd: ">From " at start of body line is an escaped "From " and must be unescaped
384        let data = b"From alice@example.com\n\
385                     Subject: Test\n\
386                     \n\
387                     >From someone we know\n"
388            .to_vec();
389        let cursor = Cursor::new(data);
390        let reader = MboxReader::new(cursor, MboxFormat::MboxRd);
391        let messages: Vec<Result<RawMessage>> = reader.collect();
392        assert_eq!(messages.len(), 1);
393        let msg = messages[0].as_ref().unwrap();
394        let body = std::str::from_utf8(&msg.body).unwrap();
395        assert!(body.contains("From someone"), "'>From' should be unescaped to 'From'");
396        assert!(!body.contains(">From"), "unescaped body should not contain '>From'");
397    }
398
399    #[test]
400    fn test_parse_mbox_three_messages_bodies() {
401        let data = create_mbox_data();
402        let cursor = Cursor::new(data);
403        let reader = MboxReader::new(cursor, MboxFormat::MboxO);
404        let messages: Vec<Result<RawMessage>> = reader.collect();
405        assert_eq!(messages.len(), 3);
406        let body0 = std::str::from_utf8(&messages[0].as_ref().unwrap().body).unwrap();
407        assert!(body0.contains("first message body"));
408        let body1 = std::str::from_utf8(&messages[1].as_ref().unwrap().body).unwrap();
409        assert!(body1.contains("reply"));
410    }
411}