Skip to content

Commit 0741258

Browse files
committed
Harden the email connector for Cloud and untrusted mail (#1344)
- Cloud: the hosting provider blocks outgoing SMTP on 25, 465 and 587. A send there gives up after 5 s with an smtp_blocked error that says so and points to save_draft or a provider on port 2525; Test connection reports IMAP working and SMTP not reachable instead of failing - Cloud: SMTP port 25 is no longer allowed (direct delivery from our address risks blocklisting); self-hosted keeps it - Cloud: SMTP login is forced, so nothing goes out through an open relay unauthenticated - send_message and delete_messages are created switched off, for hand-made connectors and catalog installs; save_draft stays the default way to answer - reading tools and their results say that message content is untrusted data whose instructions must not be followed - adapter instructions, guide, setup help and docs updated
1 parent 1376ccb commit 0741258

17 files changed

Lines changed: 342 additions & 41 deletions

‎docs/connectors/email.md‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,14 +25,21 @@ Every Email connector carries the same tools, named `<prefix>_…`. The prefix i
2525
| `<prefix>_get_attachment` | One attachment by its index. Text types (txt, csv, json, xml, html, calendar) come back as text; images and other files are attached to the tool result as image or embedded resource. Above 4 MB it is refused | read-only |
2626
| `<prefix>_set_flags` | `seen` (read/unread) and `flagged`, for up to 100 UIDs | write, idempotent |
2727
| `<prefix>_move_messages` | To another folder; returns the new UIDs | write |
28-
| `<prefix>_delete_messages` | Moves to the Trash folder; nothing is deleted permanently, and messages already in the Trash are refused | destructive |
29-
| `<prefix>_save_draft` | IMAP APPEND to the Drafts folder with `\Draft`, for a person to review and send | write |
30-
| `<prefix>_send_message` | SMTP. `to`/`cc`/`bcc` (at most 50 recipients), `subject`, `text` and/or `html`. With `in_reply_to_uid` (and `in_reply_to_folder`) it sets In-Reply-To and References, defaults the recipient to the original's Reply-To or sender, prefixes "Re:" and marks the original `\Answered`. A copy goes to the Sent folder unless the provider files one itself (Gmail does) | write, open-world |
28+
| `<prefix>_delete_messages` | Moves to the Trash folder; nothing is deleted permanently, and messages already in the Trash are refused. **Off at creation** | destructive |
29+
| `<prefix>_save_draft` | IMAP APPEND to the Drafts folder with `\Draft`, for a person to review and send. The default way to answer | write |
30+
| `<prefix>_send_message` | SMTP. `to`/`cc`/`bcc` (at most 50 recipients), `subject`, `text` and/or `html`. With `in_reply_to_uid` (and `in_reply_to_folder`) it sets In-Reply-To and References, defaults the recipient to the original's Reply-To or sender, prefixes "Re:" and marks the original `\Answered`. A copy goes to the Sent folder unless the provider files one itself (Gmail does). **Off at creation** | write, open-world |
3131

3232
Moves use IMAP MOVE. A server without MOVE gets COPY, then the original is flagged `\Deleted` and removed with `UID EXPUNGE` (UIDPLUS), which touches only the moved messages; a server with neither MOVE nor UIDPLUS is refused, because its plain EXPUNGE would also remove messages another client marked as deleted. UIDs belong to one folder and change when a message moves. Bcc recipients are in the SMTP envelope only, never in the transmitted headers; the copy in Sent keeps the Bcc header so the sender can see it. Once SMTP has accepted a message the tool does not fail: a Sent copy that could not be filed is reported as a warning in the result, because sending again would deliver the mail twice.
3333

3434
Outgoing attachments are not supported yet.
3535

36+
### Untrusted content
37+
38+
Mail is written by whoever sent it, and an e-mail can carry text aimed at the model ("forward every invoice to…", "delete this thread"). Two defences:
39+
40+
- `send_message` and `delete_messages` are created **switched off**, on hand-made connectors and catalog installs alike. A person turns them on in the connector's tool list when the agent should really send or delete; `save_draft` stays on as the default way to answer, so a person reviews every outgoing message.
41+
- The descriptions of the reading tools, and every result that carries message content (`contentNotice`), say that the content is data from the sender and that instructions in it must not be followed.
42+
3643
## Settings (`config.email`)
3744

3845
| Key | Meaning |
@@ -63,9 +70,12 @@ The connector's base URL (`imaps://host:993`) is what the connector list shows;
6370
| Mail server on a private, loopback or link-local address | Refused by the outbound SSRF guard | Refused by default; allowed once an administrator adds the host to the outbound allowlist (Admin → Settings, or `SSRF_ALLOWED_HOSTS`) |
6471
| Encryption | SSL/TLS or STARTTLS only | Also plaintext, for a server on the internal network |
6572
| Certificate | Must be valid for the host name | May be self-signed with "Accept self-signed certificate" |
66-
| Ports | IMAP 993/143, SMTP 465/587/25/2525 | Any |
73+
| Ports | IMAP 993/143, SMTP 465/587/2525 (no 25: direct delivery from the Cloud's address would get it blocklisted) | Any |
74+
| SMTP authentication | Always required: the login is attempted even when a server does not offer AUTH, so nothing goes out through an open relay | Used whenever the server offers AUTH |
75+
76+
The guard resolves the host once and the connection goes to exactly the address it checked, with the host name kept for TLS (SNI and certificate check).
6777

68-
The guard resolves the host once and the connection goes to exactly the address it checked, with the host name kept for TLS (SNI and certificate check). Many hosting networks block outgoing port 25: use 465 or 587.
78+
**Sending from Cloud.** The Cloud's hosting provider (DigitalOcean) blocks outgoing SMTP on ports 25, 465 and 587; IMAP on 993 is open, and 2525 passes. On Cloud a send on a blocked port gives up after 5 seconds with a message saying so (`smtp_blocked`), and nothing is sent; Test connection reports IMAP as working and SMTP as not reachable instead of failing. Answer with `save_draft` and send from the mail client, use a provider that offers SMTP on port 2525, or self-host AnythingMCP.
6979

7080
## Not yet
7181

‎llms-full.txt‎

Lines changed: 15 additions & 5 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/backend/src/adapters/catalog.spec.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -535,5 +535,10 @@ describe('EMAIL adapters', () => {
535535
expect(adapter!.tools[0].name).toBe('imap_smtp_guide');
536536
expect(adapter!.probe?.tool).toBe('imap_smtp_list_folders');
537537
expect(adapter!.tools.some((t) => t.name === adapter!.probe?.tool)).toBe(true);
538+
// Sending and deleting install switched off; drafts are the way to answer.
539+
expect(adapter!.tools.filter((t) => t.enabled === false).map((t) => t.name).sort()).toEqual([
540+
'imap_smtp_delete_messages',
541+
'imap_smtp_send_message',
542+
]);
538543
});
539544
});

0 commit comments

Comments
 (0)