feat(mail): event-driven SMTP send + IMAP recv client module

[ithewei]

What

Closes #883 (send/receive email like curl). Adds a new optional mail/ module with asynchronous email clients built on the hloop event loop — replacing the synchronous demo in protocol/smtp.c (kept as-is for compatibility).

Module

• mail/mime.{h,c} — MIME assembly + parsing, shared by both clients.
  • assembly: multipart/mixed + multipart/alternative, base64 attachments, RFC 2047 encoded-word for non-ASCII headers.
  • parsing: multipart split (nested), base64 / quoted-printable decode, extracts From/Subject/Date/text/html/attachments into mail_t.
  • mail_t supports multi-recipient To/Cc + attachments, with mail_set_* / mail_add_* / mail_clear helpers.
• mail/smtp_client.{h,c} — async SMTP client (C core + SmtpClient C++ wrapper). State machine: EHLO → AUTH LOGIN → MAIL FROM → RCPT TO (multi) → DATA → QUIT. Result via callback.
• mail/imap_client.{h,c} — async IMAP client (C core + ImapClient C++ wrapper). LOGIN → SELECT → SEARCH → FETCH (per id, literal {n} parsing) → LOGOUT, then MIME-parses each message and delivers via per-mail callback.
• TLS: direct TLS (SMTPS 465 / IMAPS 993) via the existing hssl abstraction.

The API/structure mirrors the existing mqtt/ module (C core + C++ wrapper, _new/_run/_stop/_free, hloop state machine, hmutex for thread-safety).

Build

--with-mail / WITH_MAIL (default OFF), wired across configure / Makefile / CMake / Bazel, mirroring the mqtt module. Requires SSL for direct TLS. Linux CI now builds with --with-mail.

Examples + docs

• examples/mail/sendmail_test.cpp, examples/mail/recvmail_test.cpp
• docs/cn/SmtpClient.md, docs/cn/ImapClient.md
• README / README-CN mention the mail client.

Scope / limitations (by design)

• Direct TLS only (SMTPS 465 / IMAPS 993); no STARTTLS (587/143). Mainstream mailboxes (QQ/163/Gmail) all offer direct-SSL ports.
• IMAP read-only minimal set (LOGIN/SELECT/SEARCH/FETCH/LOGOUT); no STORE/COPY/move/IDLE.
• No POP3 (IMAP is the modern default; POP3 has little practical value).
• MIME parsing does not transcode charset (returned as-is) to avoid an iconv dependency.

Testing

• make libhv (--with-mail --with-openssl) ✅, make sendmail_test recvmail_test ✅
• CMake build with -DWITH_MAIL=ON ✅
• mail sources compile clean under -Wall -Wextra.
• MIME build→parse round-trip verified with a standalone program (text + base64 attachment + RFC 2047 subject round-trip correctly).
• SMTP send / IMAP fetch against real mailboxes are intended for manual verification (require live accounts); CI covers compilation.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved critical security issues and multiple correctness and build findings block approval.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 5 · 6

Open (11)

• Safely encode and validate IMAP login credentials · New
• Set TLS SNI hostname for IMAP connections · New
• Prevent header injection through control characters · New
• Handle vsnprintf truncation before writing SMTP commands · New
• Set TLS SNI hostname for SMTP connections · New
• Add CMake targets for mail examples · New
• Retain partial tagged IMAP responses across reads · New
• Support whitespace in MIME base64 decoding · New
• Decode RFC 2047 encoded header values · New
• Accept SMTP RCPT TO response code 252 · New
• Dot-stuff SMTP DATA payload lines · New

What changed in this PR

Adds an optional asynchronous SMTP/IMAP client module with shared MIME handling, C/C++ APIs, direct TLS support, documentation, examples, and build integration.

Changes:

• Adds MIME assembly/parsing and SMTP/IMAP state machines.
• Wires WITH_MAIL across Make, CMake, Bazel, configuration, and CI.
• Adds mail examples and client documentation.

File	Reviewed changes and final findings
README.md	Documents mail client support; no final comments.
README-CN.md	Documents mail client support in Chinese; no final comments.
Makefile.vars	Adds mail headers; no final comments.
Makefile	Builds mail sources and examples; no final comments.
mail/​smtp_client.h	Defines SMTP C/C++ APIs; no final comments.
mail/​smtp_client.c	Implements SMTP state machine. Moderate (3 votes): DATA payload requires dot-stuffing. Moderate (2 votes): accept valid 252 recipient responses. Critical (2 votes): set TLS hostname for SNI. Moderate (1 vote): release owned loops during teardown. Critical (2 votes): handle vsnprintf truncation to prevent out-of-bounds reads.
mail/​mime.h	Defines MIME and mail APIs; no final comments.
mail/​mime.c	Implements MIME assembly/parsing. Moderate (3 votes): decode RFC 2047 encoded-word subjects. Critical (3 votes): prevent CR/LF header injection. Moderate (2 votes): accept MIME base64 line breaks. Moderate (1 vote): reject or guard NULL attachment data. Moderate (1 vote): unfold continuation lines in headers.
mail/​imap_client.h	Defines IMAP C/C++ APIs; no final comments.
mail/​imap_client.c	Implements IMAP fetching. Critical (3 votes): safely encode credentials and reject control characters. Critical (2 votes): set TLS hostname for SNI. Moderate (1 vote): release owned loops during teardown. Moderate (3 votes): retain incomplete tagged responses. Moderate (1 vote): grow or reject SEARCH results beyond 4096 IDs. Moderate (1 vote): report failed LOGOUT responses. Moderate (1 vote): use BODY.PEEK[] to avoid marking messages read.
examples/​mail/​sendmail_test.cpp	Adds SMTP usage example; no final comments.
examples/​mail/​recvmail_test.cpp	Adds IMAP usage example; no final comments.
docs/​cn/​SmtpClient.md	Documents SMTP usage; no final comments.
docs/​cn/​ImapClient.md	Documents IMAP usage; no final comments.
configure	Adds the mail configure option; no final comments.
config.ini	Adds the mail feature flag; no final comments.
CMakeLists.txt	Adds CMake mail integration. Moderate (2 votes): add CMake targets for both mail examples.
cmake/​vars.cmake	Defines mail headers; no final comments.
BUILD.bazel	Adds Bazel mail integration. Moderate (1 vote): add conditional mail example targets and filegroup entries.
.github/​workflows/​CI.yml	Enables mail compilation in CI; no final comments.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ithewei]

Thanks for the thorough review — addressed in 0cd21e9. Summary of what changed:

High

• SNI hostname (SMTP/IMAP): hio_create_socket only stores the peer address, so hio_set_hostname(io, host) is now called before hio_enable_ssl — name-based virtual SMTPS/IMAPS hosts now get proper SNI.
• vsnprintf truncation (SMTP): return value (would-be length) is clamped to the actual buffer size before writing, so a long host/address can't cause an over-read.
• Header CR/LF injection (MIME): header values with CR/LF/control chars are now forced through RFC 2047 encoding instead of the ASCII fast path.
• IMAP credential injection: LOGIN username/password are quoted (with "/\ escaping) and control characters are rejected up front.

Medium

• base64 with line breaks (MIME): hv_base64_decode rejects CR/LF, so a whitespace-stripping wrapper was added — previously any wrapped attachment decoded to 0 bytes. Verified a 5000-byte attachment now round-trips.
• RFC 2047 decode on parse: Subject/etc. encoded-words are decoded when parsing, so build→parse round-trips to the original text.
• IMAP partial tagged response: a tagged line is only treated as final once a full CRLF-terminated line has arrived, so responses split across reads aren't discarded.
• RCPT TO 252: accepted as success.
• DATA dot-stuffing: body lines starting with . are dot-stuffed so a lone . line can't terminate DATA early.
• CMake example targets: examples/CMakeLists.txt now builds sendmail_test/recvmail_test under WITH_MAIL.
• Also made attachment decoding binary-safe (track decoded length instead of strlen, which truncated at embedded NULs), and switched FETCH to BODY.PEEK[] so reading doesn't set \Seen.

Not changed (minor / out of scope for this module): SEARCH id cap >4096, reporting a failed LOGOUT, header continuation unfolding — can follow up if needed.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Multiple unresolved critical security and correctness issues affect the SMTP, IMAP, MIME, and public API changes.

Review effort: Lite
Findings: 9 · 2

Open (11)

• Validate IMAP literal lengths before parsing · New
• Reject CR/LF in mailbox and search criteria · New
• Enable peer verification by default for IMAPS · New
• Validate empty and negative Base64 input lengths · New
• Handle malformed encoded-word decoding safely · New
• Reject CR/LF in mailbox address headers · New
• Resolve mail_t definition conflict with SMTP API · New
• Reject CR/LF in SMTP envelope addresses · New
• Enable peer verification by default for SMTP TLS · New
• Add mail example targets to Bazel build · New
• Add CMake targets for mail examples

Resolved since last review (10)

• Set TLS SNI hostname for SMTP connections
• Handle vsnprintf truncation before writing SMTP commands
• Prevent header injection through control characters
• Set TLS SNI hostname for IMAP connections
• Safely encode and validate IMAP login credentials
• Dot-stuff SMTP DATA payload lines
• Accept SMTP RCPT TO response code 252
• Decode RFC 2047 encoded header values
• Support whitespace in MIME base64 decoding
• Retain partial tagged IMAP responses across reads

Previously missed (4)

In code that hasn't changed since last review

Report failed FETCH responses

mail/​imap_client.c:183

ok is computed but ignored in this no-literal path. A tagged NO/BAD response to FETCH is consumed as a successful message ID, so the client advances and can eventually report done(0) despite the fetch failing. Report the error and close instead of returning success when ok is false.

This issue also appears on line 298 of the same file.

Unfold continuation lines in RFC 5322 headers

mail/​mime.c:410

find_header intentionally returns only one physical line, so folded RFC 5322 headers are not unfolded. A folded Content-Type commonly puts the boundary parameter on the continuation line, causing multipart messages and attachments to be skipped; unfold continuations before parsing header values.

Parse display names and addresses separately

mail/​mime.c:634

mail_addr_t.addr is documented as the mailbox address, but this stores the entire decoded From field. For From: Alice <alice@example.com>, callers receive Alice <alice@example.com> as from.addr and no from.name, producing an invalid address if the parsed mail is reused for SMTP. Split the display name and angle-address into the two fields.

Buffer partial SMTP response lines

mail/​smtp_client.c:119

This parser only examines the bytes from one read callback. TCP/TLS may split a single 220 or 250 line across callbacks; the partial line is then discarded and the state machine waits forever for a response it already consumed. Keep an accumulated response buffer and parse only complete lines.