security: download-path confinement, CRLF rejection, resource limits

[lucagattoni]

What this delivers

Three security-hardening fixes to the email tools, rebased cleanly onto current main and with docs harmonized into the new multi-file docs/ structure (post-#205).

This supersedes #201, which was branched a week ago and now conflicts with the docs reorganization (#205) and the pyright/tooling changes (#204). Same fixes, cleanly re-homed.

Fixes

1. download_attachment path confinement — save paths are confined to attachment_download_dir (default ~/Downloads). A save_path escaping it via .. or a symlink (including a final-component symlink) is rejected, so attacker-controlled attachment bytes can't be written over ~/.ssh/authorized_keys, a crontab, or the config file. New attachment_download_dir setting + MCP_EMAIL_SERVER_ATTACHMENT_DOWNLOAD_DIR.
2. CRLF injection rejection — reject CR/LF in recipients, header values, and attachment paths. Closes SMTP-envelope injection via bcc (handed to aiosmtplib without being placed in a header).
3. Resource-exhaustion ceilings — page_size ≤ 500, ≤ 100 email_ids per call, and a 25 MB attachment cap guard against self-DoS from unbounded tool inputs.

Rebase / integration notes

• Adopted upstream's robust _decoded_payload in the extracted _find_attachment_in_message helper (upstream added that decoder after this branch was first written).
• Typed _reject_crlf as Iterable[str | None] to satisfy the pyright check added in chore: add pyright checks and update Python tooling #204.
• Docs distributed the idiomatic way: security.md (attachment access rewrite, HTTP-transport = not-auth, new "Message and input limits"), transports.md (unauthenticated-gateway warning under DNS-rebinding), configuration.md (setting + env rows), and corrected now-stale download_attachment guidance in tools.md/troubleshooting.md.
• E2E: download_attachment confinement required pointing MCP_EMAIL_SERVER_ATTACHMENT_DOWNLOAD_DIR at the GreenMail test's tmp_path, or the roundtrip download is rejected.

Test plan

• uv run pytest -q — 578 passed (new: test_crlf_injection.py, test_download_path_confinement.py, test_resource_limits.py)
• uv run ruff check / ruff format --check — clean
• uv run pyright — 0 errors (chore: add pyright checks and update Python tooling #204's check)
• mkdocs build --strict — builds, no broken anchors
• prettier --check docs/*.md — clean

Companion to #209 (permission model). The two are independent at the code level; when both land, whichever merges second needs a small app.py rebase where they both touch send_email/save_to_mailbox.

🤖 Generated with Claude Code

https://claude.ai/code/session_013pd8meRq4jSiqaLq715nSD

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.7%. Comparing base (81dd623) to head (e39692f).

Additional details and impacted files

@@           Coverage Diff           @@
##            main    #210     +/-   ##
=======================================
+ Coverage   92.5%   92.7%   +0.1%     
=======================================
  Files         10      10             
  Lines       2013    2074     +61     
  Branches     310     320     +10     
=======================================
+ Hits        1863    1923     +60     
- Misses       107     109      +2     
+ Partials      43      42      -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Wh1isper]

Thank you for putting together this security hardening work and for documenting the threat model so clearly.

Since this PR was opened, #212 has landed a substantial architecture rewrite that addresses these concerns through the new application boundaries:

• shared application validation now rejects C0/DEL control characters, including CR and LF, before provider access;
• request, provider-work, attachment, aggregate, and serialized-result limits are centrally owned and enforced;
• attachment writes now require explicit current policy, fresh authority checks, bounded payloads, no-follow path traversal, owner/permission checks, and race-resistant atomic writes.

The attachment path contract was also intentionally resolved differently from this PR: compatibility preserves the caller's exact destination rather than confining it under a configured download root, with the filesystem defenses above providing the security boundary.

As a result, the original issues are either covered by #212 or superseded by the accepted exact-destination design, and this branch now conflicts with the rewritten architecture. I’m closing this PR as superseded. Thank you again for the careful contribution; it helped highlight the boundaries that needed explicit treatment.