@aidalinfo/email-mcp 0.1.1 → 0.3.0

package/README.md

@@ -1,69 +1,142 @@
 # @aidalinfo/email-mcp
 
-MCP server that lets an agent **send email** through **Scaleway Transactional Email (TEM)**, from
-**one fixed sender** (e.g. `noreply@pulsemyit.fr`) to an **allowlist of recipients** only.
+MCP server that lets agents **send email** through **Scaleway Transactional Email (TEM)**, from
+**one fixed sender** (`noreply@pulsemyit.fr`) to an **allowlist of recipients** only.
+
+It runs either **locally over stdio** (one agent, as before) or as a **central server over
+Streamable HTTP** shared by the Hermes agents: one revocable key per agent, Scaleway credentials
+held by the server only.
 
 ```text
-Agent Pulse / Claude
-        │  MCP (stdio)
-        ▼
-@aidalinfo/email-mcp ── allowlist ── preview → human approval → confirm ── quota ── audit (JSON lines)
-        │  X-Auth-Token (dedicated IAM application)
-        ▼
-Scaleway TEM  POST /transactional-email/v1alpha1/regions/{region}/emails
+Agent Hermes A ─┐  Streamable HTTP + Authorization: Bearer emk_… (one key per agent)
+Agent Hermes B ─┤
+                ▼
+@aidalinfo/email-mcp (central, Coolify worker)
+   auth ── allowlist ── preview → human approval → send (token + idempotency_key) ── quotas ── ledger ── audit
+   │  X-Auth-Token (dedicated IAM application, TEM on one project)          ▲
+   ▼                                                                        │ webhook (Topics and Events)
+Scaleway TEM  /transactional-email/v1alpha1/regions/{region}/…  ───────────┘
+              smtp.tem.scaleway.com:2465 (emails above the 2 MB of the API)
 ```
 
+**Two ways out.** The TEM API refuses any email above **2 MB** (attachments included, base64
+counted, not raisable); TEM over SMTP accepts **50 MB**. By default (`EMAIL_SEND_VIA=auto`) an email
+leaves through the API up to ~1.9 MB and through SMTP above, with the same credentials (SMTP user =
+project id, password = the secret key) — attachments then go up to **35 MB** in total. `api` keeps
+everything on the API (2 MB), `smtp` sends everything over SMTP. SMTP returns no TEM id:
+`email_status` with the `idempotency_key` finds them once TEM lists the email (by the message id of
+the SMTP reply, else by sender, subject and date), usually within a minute; webhook events of an
+SMTP send are kept from then on.
+
 Guarantees, all enforced server-side:
 
 - **The sender is configuration, not an argument.** `EMAIL_FROM` / `EMAIL_FROM_NAME` / `EMAIL_REPLY_TO`
-  come from the environment; no tool parameter can change them.
+  come from the environment. Unknown tool arguments (`from`, `headers`, `Return-Path`…) are discarded;
+  there is no custom header and no bcc.
 - **Allowlisted recipients only.** `EMAIL_ALLOWED_RECIPIENTS` lists exact addresses and whole
   domains (`@pulsemyit.fr` — not its subdomains). No wildcard. Empty → the server refuses to start.
-  A single recipient outside the list (in `to` or `cc`) refuses the whole email. There is **no bcc**.
-- **Two steps.** Without `confirmToken`, `email_send` only **previews**: full headers, full text
-  body, HTML source, message digest — nothing is sent. The token it returns is an HMAC bound to the
-  **exact message** (sender, recipients, subject, bodies) and to the sender domain's state, valid
-  5 minutes, **single use** (a replayed token never sends twice), and only for this process.
-- **Sender domain checked** before every preview and every send: it must exist in the configured
-  project and be `checked` (SPF + DKIM verified).
-- **Limits:** recipients per email (`EMAIL_MAX_RECIPIENTS`, default 10, hard cap 50) and sends per
-  sliding hour (`EMAIL_MAX_PER_HOUR`, default 20, hard cap 500), per process.
-- **Kill switch:** when `EMAIL_KILL_SWITCH_FILE` exists, every send is refused at once — checked
-  at the preview and again right before sending.
-- **Audit:** one JSON line per preview / send / refusal / failure on stderr (and `EMAIL_AUDIT_LOG_FILE`):
-  sender, recipients, subject, message digest, TEM email ids, error code, Pulse approval id.
-  **Bodies are never logged** — the digest ties an entry to its preview.
-- **No raw API tool, no attachments, no custom headers**: the server can make exactly three
-  Scaleway calls (find the sender domain, create an email, read an email).
-- **Header injection:** bare addresses only (no display names), subjects with line breaks or
-  control characters are refused.
+  A client may be narrowed further (`allowedRecipients`), never widened. One recipient outside → the
+  whole email is refused.
+- **Preview, then send.** `email_preview` checks everything and sends nothing; it returns a token —
+  HMAC bound to the client, the `idempotency_key`, the **exact message** (sender, recipients,
+  subject, bodies, attachment contents) and the sender domain's state — valid 5 minutes, single use,
+  for this process only. `email_send` refuses without it.
+- **Idempotency.** `idempotency_key` is required. A key sends at most once per client: a retry with
+  the same message returns the original TEM ids, a different message under the same key is
+  refused, a send with an unknown outcome blocks its key. Over HTTP the ledger is persisted
+  (`EMAIL_STATE_DIR`), so a restart does not forget it.
+- **Client keys** (HTTP): `Authorization: Bearer emk_…`, 256 random bits, one per agent. The server
+  stores **hashes only**, re-reads the clients file on change (add, rotate, revoke without restart)
+  and refuses everything while that file is invalid (fail-closed). Keys are never logged.
+- **Quotas:** per client and server-wide, per sliding hour and per 24 h (`EMAIL_MAX_PER_HOUR`,
+  `EMAIL_MAX_PER_DAY`, client `maxPerHour` / `maxPerDay`), in memory.
+- **Kill switch:** when `EMAIL_KILL_SWITCH_FILE` exists, every send is refused — checked at the
+  preview and again right before sending.
+- **Attachments by reference only.** The agent names a configured **source** and a **reference**
+  inside it (e.g. a Pulse Chat vault file id) — never a local path nor a URL. The server fetches it
+  (https, no redirect, timeout, size cap while reading), checks the type against an allowlist, the
+  extension and the leading bytes, and binds its sha256 to the preview. A document changed between
+  preview and send → refused. No source configured → `capability_unavailable`.
+- **Versioned templates** for routines: `name@version` JSON files, variables declared and bounded,
+  escaped in HTML, refused with control characters in the subject. A client can be **templates-only**.
+- **Audit:** one JSON line per preview / send / replay / refusal / failure on stderr (and
+  `EMAIL_AUDIT_LOG_FILE`): client, sender, recipients, subject, message digest, template, attachment
+  type/size/sha256, TEM ids, idempotency key, error code, Pulse approval id. **No body, no attachment
+  content or name, no key.** Every line and every error goes through a central redactor (Scaleway
+  key, client keys, source tokens, webhook secret, Authorization headers).
+- **Bounded reads:** `email_status` (own sends only, 10 emails per key, 5 last attempts, 20 events),
+  `email_suppressions` (20 allowed addresses at most — no probing of arbitrary addresses).
+- **No raw API tool**: the server makes exactly five Scaleway API calls (find the sender domain,
+  create an email, read an email, list its own emails after an SMTP send, read the blocklist of one
+  address), plus the SMTP submission of emails above 2 MB.
 
 ## Tools
 
 | Tool | What |
 |---|---|
-| `email_config` | Sender, Reply-To, sender domain status, allowed recipients, limits, quota left this hour, kill switch. **Start here.** |
-| `email_send` | `to[]`, `cc[]?`, `subject`, `text` (required), `html?`, `approvalId?`, `confirmToken?`. Preview, then send with the token. |
-| `email_status` | Delivery status of an email **sent by this sender** (TEM id from `email_send`): `new`, `sending`, `sent`, `failed`, `canceled`, with the last attempts. Other emails of the project (e.g. an application's) are reported `not_found`. |
+| `email_config` | Client id, sender, Reply-To, domain status, allowed recipients, quotas left, templates, attachment sources, webhook, kill switch. **Start here.** |
+| `email_preview` | `to[]`, `cc[]?`, `subject` + `text` (+ `html?`) **or** `template {name, version, variables}`, `attachments[]?` (`{source, ref, filename?}`), `idempotency_key`, `approvalId?`. Nothing is sent; returns the `confirmToken`. |
+| `email_send` | Same arguments + `confirmToken`. Sends once per `idempotency_key`. |
+| `email_status` | By `emailId` or `idempotency_key`: TEM status (`new`, `sending`, `sent`, `failed`, `canceled`), last attempts, webhook events (`email_delivered`, `email_dropped`, `email_spam`, `email_mailbox_not_found`…). Own sends only. |
+| `email_templates` | Templates this client may use, with their variables. |
+| `email_suppressions` | Whether allowed addresses are on TEM's blocklist (bounce, full mailbox…). |
 
-### The two-step protocol
+### The protocol
 
-1. `email_send({ to, subject, text })` → preview + `confirmToken`. **Nothing is sent.**
+1. `email_preview({ to, subject, text, idempotency_key })` → preview + `confirmToken`. **Nothing is sent.**
 2. Show the preview to the human (in Pulse Chat) and wait for an explicit approval.
-3. `email_send({ to, subject, text, confirmToken, approvalId })` with the **same arguments** → sent.
-   Any change (one more recipient, a reworded sentence) → `confirmation_invalid`: preview again.
+3. `email_send({ …same arguments, idempotency_key, confirmToken, approvalId })` → sent.
+   Any change (one more recipient, a reworded sentence, another attachment version) → `confirmation_invalid`.
+4. `email_status({ idempotency_key })` to follow delivery.
 
-The token proves the message is the one previewed; it does **not** prove a human approved it
-(the agent holds the token). The human approval is Pulse's own gate — `approvalId` is recorded
-in the audit trail for correlation (`verified: false`), it is not an authorisation.
+The token proves the message is the one previewed; it does **not** prove a human approved it (the
+agent holds the token). The human approval is Pulse's own gate — `approvalId` is recorded in the
+audit trail for correlation (`verified: false`), it is not an authorisation.
 
 ### Error codes
 
 `invalid_request` · `recipient_not_allowed` · `domain_not_ready` · `rate_limited` · `refused`
-(kill switch) · `confirmation_invalid` · `permission_missing` (API key lacks TEM rights) ·
-`not_found` · `transient` · **`unknown_outcome`** — the send request was cut off (timeout, network,
-5xx): the email **may have left**. The token is consumed and the quota slot kept; check
-`email_status` or the TEM console before sending again — never retry blindly.
+(kill switch, templates-only, ledger not writable) · `confirmation_invalid` · `idempotency_conflict` ·
+`attachment_refused` · `capability_unavailable` (attachments, templates or webhook not configured) ·
+`permission_missing` (API key lacks TEM rights) · `not_found` · `transient` · **`unknown_outcome`** —
+the send request was cut off (timeout, network, 5xx): the email **may have left**. The key is burnt
+and the quota slot kept; check `email_status` or the TEM console — never resend blindly under a new key.
+
+## Running it
+
+### Locally (stdio)
+
+```bash
+claude mcp add email --scope user \
+  -e SCW_SECRET_KEY=... \
+  -e EMAIL_PROJECT_ID=<project-uuid> \
+  -e EMAIL_FROM=noreply@pulsemyit.fr -e EMAIL_FROM_NAME="Pulse myIT" \
+  -e EMAIL_ALLOWED_RECIPIENTS=@pulsemyit.fr,@aidalinfo.fr \
+  -e EMAIL_KILL_SWITCH_FILE=$HOME/.email-mcp.stop \
+  -e EMAIL_STATE_DIR=$HOME/.email-mcp \
+  -- npx -y @aidalinfo/email-mcp
+```
+
+### Central (HTTP)
+
+```bash
+npx -y @aidalinfo/email-mcp keygen hermes-ops   # prints the key (once) and the clients-file entry
+EMAIL_MCP_TRANSPORT=http EMAIL_STATE_DIR=/data EMAIL_MCP_CLIENTS_FILE=/config/clients.json … npx -y @aidalinfo/email-mcp
+```
+
+Container image: [`Dockerfile`](Dockerfile) (build from the repo root), Coolify compose:
+[`deploy/compose.yaml`](deploy/compose.yaml). Endpoints: `POST /mcp` (Streamable HTTP, stateless,
+JSON responses), `GET /health`, `POST /webhooks/tem/<secret>`.
+
+Operations — deployment, key rotation, kill switch, webhook, acceptance without a real send:
+[`docs/exploitation.md`](docs/exploitation.md).
+
+An agent registers it with its own key:
+
+```bash
+claude mcp add --transport http email https://email.mcp.pulsemyit.fr/mcp \
+  --header "Authorization: Bearer emk_…"
+```
 
 ## Scaleway setup
 
@@ -71,8 +144,9 @@ in the audit trail for correlation (`verified: false`), it is not an authorisati
    and region, publish the SPF, DKIM (and MX/DMARC recommended) records, wait for status
    **`checked`**. `email_config` (or `list_tem_domains` of `@aidalinfo/scaleway-mcp`) shows it.
 2. **Identity:** IAM → create a **dedicated application** (e.g. `email-mcp`), a policy granting it
-   Transactional Email permissions **scoped to that project only**, and an API key for it. Do not
-   reuse a personal key or the key of another MCP.
+   `TransactionalEmailFullAccess` (send, read emails, read blocklists) **scoped to that project
+   only**, and an API key for it. Do not reuse a personal key or the key of another MCP. This key
+   lives in the server's environment only, never in an agent's configuration.
 3. **Allowlist:** start narrow (`@pulsemyit.fr,@aidalinfo.fr`), add external addresses one by one.
 
 ## Configuration
@@ -85,41 +159,50 @@ startup (fail-closed) instead of guessing.
 | `SCW_SECRET_KEY` | yes | | Secret key of the dedicated IAM application |
 | `EMAIL_PROJECT_ID` | yes | `SCW_DEFAULT_PROJECT_ID` | Project of the TEM domain |
 | `EMAIL_REGION` | | `fr-par` | `fr-par`, `nl-ams`, `pl-waw` |
-| `EMAIL_FROM` | yes | | Bare address, e.g. `noreply@pulsemyit.fr` |
+| `EMAIL_FROM` | yes | (`noreply@pulsemyit.fr` in the image) | Bare address |
 | `EMAIL_FROM_NAME` | | | Display name, e.g. `Pulse myIT` |
 | `EMAIL_REPLY_TO` | | | Fixed Reply-To (sent as an additional header) |
 | `EMAIL_ALLOWED_RECIPIENTS` | yes | | `a@x.fr,@domain.fr` — no wildcard |
 | `EMAIL_MAX_RECIPIENTS` | | 10 | to + cc, hard cap 50 |
-| `EMAIL_MAX_PER_HOUR` | | 20 | sliding hour, per process, hard cap 500 |
+| `EMAIL_MAX_PER_HOUR` / `EMAIL_MAX_PER_DAY` | | 20 / 200 | server-wide, hard caps 500 / 5000 |
 | `EMAIL_KILL_SWITCH_FILE` | | | `touch` it to stop all sends |
 | `EMAIL_AUDIT_LOG_FILE` | | | JSON lines, mode 600 |
-
-## Register in Claude Code
-
-```bash
-claude mcp add email --scope user \
-  -e SCW_SECRET_KEY=... \
-  -e EMAIL_PROJECT_ID=<project-uuid> \
-  -e EMAIL_FROM=noreply@pulsemyit.fr -e EMAIL_FROM_NAME="Pulse myIT" \
-  -e EMAIL_ALLOWED_RECIPIENTS=@pulsemyit.fr,@aidalinfo.fr \
-  -e EMAIL_KILL_SWITCH_FILE=$HOME/.email-mcp.stop \
-  -- npx -y @aidalinfo/email-mcp
+| `EMAIL_STATE_DIR` | HTTP | | Send ledger `ledger.json` (mode 600, 30-day retention) |
+| `EMAIL_TEMPLATES_DIR` | | | `*.json` templates, loaded at startup |
+| `EMAIL_ATTACHMENT_SOURCES` | | | JSON `[{id, baseUrl (https), tokenEnv?, authScheme?, clients?}]` |
+| `EMAIL_ATTACHMENT_TYPES` | | pdf, png, jpeg, txt, csv | also docx, xlsx |
+| `EMAIL_SEND_VIA` | | `auto` | `auto` (API ≤ 2 MB, SMTP above), `api`, `smtp` |
+| `EMAIL_SMTP_PORT` | | 2465 | 2465 / 465 (TLS), 2587 / 587 (STARTTLS) — Scaleway Instances block 465 and 587 by default |
+| `EMAIL_MAX_ATTACHMENTS` / `EMAIL_MAX_ATTACHMENT_BYTES` | | 5 / 35 000 000 (2 000 000 with `api`) | caps 10 / 35 000 000 (10 000 000 with `api`), total |
+| `EMAIL_MCP_TRANSPORT` | | `stdio` | `http` in the image |
+| `EMAIL_MCP_HOST` / `EMAIL_MCP_PORT` | | `127.0.0.1` / 8080 | `0.0.0.0` in the image |
+| `EMAIL_MCP_CLIENTS_FILE` or `EMAIL_MCP_CLIENTS` | HTTP | | clients JSON (below) |
+| `EMAIL_WEBHOOK_SECRET` | | | 32–128 chars, enables `POST /webhooks/tem/<secret>` |
+| `EMAIL_MCP_ALLOWED_ORIGINS` | | | Origins allowed to call `/mcp` (none by default) |
+
+Clients file — hashes only, as printed by `email-mcp keygen`:
+
+```json
+[
+  { "id": "hermes-ops", "keys": ["sha256:<hex>"], "maxPerHour": 10, "maxPerDay": 50 },
+  { "id": "hermes-routines", "keys": ["sha256:<hex>"], "templatesOnly": true, "allowedRecipients": "@pulsemyit.fr" },
+  { "id": "old-agent", "keys": ["sha256:<hex>"], "disabled": true }
+]
 ```
 
-Emergency stop, no restart needed:
-
-```bash
-touch ~/.email-mcp.stop
-```
+Template file (`EMAIL_TEMPLATES_DIR/rapport-hebdo@1.json`, see [`deploy/templates/`](deploy/templates/)):
+`name`, `version`, `subject`, `text`, `html?`, `variables {name: {maxLength, required?, description?}}`,
+`clients?`. A new wording is a **new version**; routines pin the version they were approved with.
 
 ## Development
 
 ```bash
 npm install                      # at the repo root (npm workspaces)
-npm test -w @aidalinfo/email-mcp # tsc + jest (TEM is faked, nothing is sent)
+npm test -w @aidalinfo/email-mcp # tsc + jest (TEM faked, nothing is sent; HTTP tests on a local port)
 npm run build -w @aidalinfo/email-mcp
 node packages/email-mcp/smoke.mjs  # starts the server over stdio and lists its tools; SMOKE_CALL_CONFIG=1 also calls email_config
+node packages/email-mcp/scripts/deploy-check.mjs  # against a running HTTP server, preview only (see docs/exploitation.md)
 ```
 
-`smoke.mjs` never sends anything. To test a real send, register the server with an allowlist
-holding only your own address and go through the preview → confirm flow.
+Neither script sends anything. To test a real send, use an allowlist holding only your own
+address and go through preview → confirmation.

package/deploy/clients.example.json

@@ -0,0 +1,4 @@
+[
+  { "id": "hermes-ops", "keys": ["sha256:0000000000000000000000000000000000000000000000000000000000000000"], "maxPerHour": 10, "maxPerDay": 50 },
+  { "id": "hermes-routines", "keys": ["sha256:1111111111111111111111111111111111111111111111111111111111111111"], "templatesOnly": true, "allowedRecipients": "@pulsemyit.fr" }
+]

package/deploy/compose.yaml

@@ -0,0 +1,50 @@
+# Central email MCP — Coolify (docker compose) on a WORKER server, never on the management/routing host.
+# No secret here: set them in Coolify's environment variables (marked secret), see ../.env.example.
+#
+# Public exposure stays OFF until the DNS record email.mcp.pulsemyit.fr exists and is validated:
+# do not set a domain in Coolify before that (see docs/exploitation.md → Exposure).
+services:
+  email-mcp:
+    image: ${EMAIL_MCP_IMAGE:-email-mcp:0.2.0}
+    restart: unless-stopped
+    environment:
+      EMAIL_MCP_TRANSPORT: http
+      EMAIL_MCP_HOST: 0.0.0.0
+      EMAIL_MCP_PORT: 8080
+      EMAIL_STATE_DIR: /data
+      EMAIL_MCP_CLIENTS_FILE: /config/clients.json
+      EMAIL_TEMPLATES_DIR: /config/templates
+      EMAIL_KILL_SWITCH_FILE: /data/STOP
+      EMAIL_AUDIT_LOG_FILE: /data/audit.jsonl
+      EMAIL_FROM: noreply@pulsemyit.fr
+      EMAIL_FROM_NAME: ${EMAIL_FROM_NAME:-Pulse myIT}
+      EMAIL_REGION: ${EMAIL_REGION:-fr-par}
+      # API up to 2 MB per email, SMTP (port 2465, outbound) above — see README
+      EMAIL_SEND_VIA: ${EMAIL_SEND_VIA:-auto}
+      EMAIL_SMTP_PORT: ${EMAIL_SMTP_PORT:-2465}
+      # required, no default — the container exits with a clear message when one is missing
+      SCW_SECRET_KEY: ${SCW_SECRET_KEY:?SCW_SECRET_KEY is required}
+      EMAIL_PROJECT_ID: ${EMAIL_PROJECT_ID:?EMAIL_PROJECT_ID is required}
+      EMAIL_ALLOWED_RECIPIENTS: ${EMAIL_ALLOWED_RECIPIENTS:?EMAIL_ALLOWED_RECIPIENTS is required}
+      # optional
+      EMAIL_REPLY_TO: ${EMAIL_REPLY_TO:-}
+      EMAIL_MAX_PER_HOUR: ${EMAIL_MAX_PER_HOUR:-20}
+      EMAIL_MAX_PER_DAY: ${EMAIL_MAX_PER_DAY:-200}
+      EMAIL_WEBHOOK_SECRET: ${EMAIL_WEBHOOK_SECRET:-}
+      EMAIL_ATTACHMENT_SOURCES: ${EMAIL_ATTACHMENT_SOURCES:-}
+      PULSE_VAULT_TOKEN: ${PULSE_VAULT_TOKEN:-}
+    volumes:
+      - email-mcp-data:/data
+      # clients.json (key hashes only) and templates/*.json, read-only
+      - ./config:/config:ro
+    expose:
+      - "8080"
+    read_only: true
+    tmpfs:
+      - /tmp
+    cap_drop: [ALL]
+    security_opt: ["no-new-privileges:true"]
+    mem_limit: 256m
+
+volumes:
+  email-mcp-data:

package/deploy/templates/rapport-hebdo@1.json

@@ -0,0 +1,13 @@
+{
+  "name": "rapport-hebdo",
+  "version": 1,
+  "description": "Rapport hebdomadaire d'une routine Hermes",
+  "subject": "Rapport de la semaine {{semaine}}",
+  "text": "Bonjour {{prenom}},\n\nle rapport de la semaine {{semaine}} est disponible :\n{{resume}}\n\n— Pulse myIT (message automatique, ne pas répondre)",
+  "html": "<p>Bonjour {{prenom}},</p><p>Le rapport de la semaine {{semaine}} est disponible :</p><p>{{resume}}</p><p>— Pulse myIT (message automatique, ne pas répondre)</p>",
+  "variables": {
+    "semaine": { "maxLength": 10, "description": "Numéro de semaine, ex. 45" },
+    "prenom": { "maxLength": 60 },
+    "resume": { "maxLength": 4000, "description": "Résumé en texte brut (échappé dans le HTML)" }
+  }
+}

package/dist/attachments.js

@@ -0,0 +1,207 @@
+import { createHash } from "node:crypto";
+import { intIn } from "./config.js";
+import { EmailError } from "./errors.js";
+import { redactor } from "./redact.js";
+/** Types an attachment may have, with their extensions and leading bytes (checked, not trusted from the source). */
+export const KNOWN_TYPES = {
+    "application/pdf": { exts: ["pdf"], magic: [0x25, 0x50, 0x44, 0x46, 0x2d] },
+    "image/png": { exts: ["png"], magic: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] },
+    "image/jpeg": { exts: ["jpg", "jpeg"], magic: [0xff, 0xd8, 0xff] },
+    "text/plain": { exts: ["txt"], text: true },
+    "text/csv": { exts: ["csv"], text: true },
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": { exts: ["docx"], magic: [0x50, 0x4b, 0x03, 0x04] },
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { exts: ["xlsx"], magic: [0x50, 0x4b, 0x03, 0x04] },
+};
+export const DEFAULT_TYPES = ["application/pdf", "image/png", "image/jpeg", "text/plain", "text/csv"];
+export const DEFAULT_MAX_ATTACHMENTS = 5;
+export const HARD_MAX_ATTACHMENTS = 10;
+export const DEFAULT_MAX_ATTACHMENT_BYTES = 2_000_000;
+export const HARD_MAX_ATTACHMENT_BYTES = 10_000_000;
+/** With SMTP (TEM: 50 MB per email): 35 MB of files, ~47 MB once base64-encoded, leaves room for the bodies. */
+export const SMTP_MAX_ATTACHMENT_BYTES = 35_000_000;
+export const FETCH_TIMEOUT_MS = 60_000;
+const SOURCE_ID_RE = /^[a-z0-9][a-z0-9-]{0,39}$/;
+/** Path segments starting with a letter or digit: no "..", no "/x", no "//", no query. */
+export const REF_RE = /^[A-Za-z0-9][A-Za-z0-9._~-]*(?:\/[A-Za-z0-9][A-Za-z0-9._~-]*)*$/;
+const FILENAME_RE = /^[A-Za-z0-9][A-Za-z0-9 ._()-]{0,99}$/;
+/**
+ * EMAIL_ATTACHMENT_SOURCES: JSON list of `{ "id", "baseUrl", "tokenEnv"?, "authScheme"?, "clients"? }`.
+ * The token itself never sits in that JSON: `tokenEnv` names the env var holding it.
+ */
+export function loadAttachmentConfig(env, warnings = [], sendVia = "api") {
+    const raw = env.EMAIL_ATTACHMENT_SOURCES?.trim();
+    const sources = [];
+    if (raw) {
+        let list;
+        try {
+            list = JSON.parse(raw);
+        }
+        catch {
+            throw new Error("EMAIL_ATTACHMENT_SOURCES is not valid JSON");
+        }
+        if (!Array.isArray(list))
+            throw new Error("EMAIL_ATTACHMENT_SOURCES must be a JSON list");
+        for (const s of list) {
+            const id = s?.id;
+            if (typeof id !== "string" || !SOURCE_ID_RE.test(id))
+                throw new Error("EMAIL_ATTACHMENT_SOURCES: each source needs an id matching [a-z0-9-]");
+            if (sources.some((x) => x.id === id))
+                throw new Error(`EMAIL_ATTACHMENT_SOURCES: duplicate source "${id}"`);
+            let url;
+            try {
+                url = new URL(String(s.baseUrl));
+            }
+            catch {
+                throw new Error(`EMAIL_ATTACHMENT_SOURCES[${id}]: baseUrl is not a URL`);
+            }
+            if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
+                throw new Error(`EMAIL_ATTACHMENT_SOURCES[${id}]: baseUrl must be https, without credentials, query or fragment`);
+            }
+            const baseUrl = url.href.endsWith("/") ? url.href : `${url.href}/`;
+            let authorization;
+            if (s.tokenEnv !== undefined) {
+                const token = typeof s.tokenEnv === "string" ? env[s.tokenEnv]?.trim() : undefined;
+                if (!token)
+                    throw new Error(`EMAIL_ATTACHMENT_SOURCES[${id}]: env var ${String(s.tokenEnv)} (tokenEnv) is missing or empty`);
+                redactor.add(token);
+                const scheme = typeof s.authScheme === "string" ? s.authScheme : "Bearer";
+                if (!/^[A-Za-z]{1,20}$/.test(scheme))
+                    throw new Error(`EMAIL_ATTACHMENT_SOURCES[${id}]: invalid authScheme`);
+                authorization = `${scheme} ${token}`;
+            }
+            if (s.clients !== undefined && (!Array.isArray(s.clients) || s.clients.some((c) => typeof c !== "string"))) {
+                throw new Error(`EMAIL_ATTACHMENT_SOURCES[${id}]: clients must be a list of client ids`);
+            }
+            sources.push({ id, baseUrl, authorization, clients: s.clients });
+        }
+    }
+    const types = (env.EMAIL_ATTACHMENT_TYPES?.trim() ? env.EMAIL_ATTACHMENT_TYPES.split(",") : DEFAULT_TYPES).map((t) => t.trim().toLowerCase()).filter(Boolean);
+    for (const t of types)
+        if (!Object.hasOwn(KNOWN_TYPES, t))
+            throw new Error(`EMAIL_ATTACHMENT_TYPES: unsupported type "${t}" (supported: ${Object.keys(KNOWN_TYPES).join(", ")})`);
+    return {
+        sources,
+        types,
+        maxCount: intIn(env.EMAIL_MAX_ATTACHMENTS?.trim() || undefined, "EMAIL_MAX_ATTACHMENTS", DEFAULT_MAX_ATTACHMENTS, HARD_MAX_ATTACHMENTS, warnings),
+        maxTotalBytes: sendVia === "api"
+            ? intIn(env.EMAIL_MAX_ATTACHMENT_BYTES?.trim() || undefined, "EMAIL_MAX_ATTACHMENT_BYTES", DEFAULT_MAX_ATTACHMENT_BYTES, HARD_MAX_ATTACHMENT_BYTES, warnings)
+            : intIn(env.EMAIL_MAX_ATTACHMENT_BYTES?.trim() || undefined, "EMAIL_MAX_ATTACHMENT_BYTES", SMTP_MAX_ATTACHMENT_BYTES, SMTP_MAX_ATTACHMENT_BYTES, warnings),
+    };
+}
+const refused = (m) => new EmailError("attachment_refused", `attachment_refused: ${m}`);
+function startsWith(buf, magic) {
+    return buf.length >= magic.length && magic.every((b, i) => buf[i] === b);
+}
+/**
+ * Resolves attachment references itself: the agent names a configured source and a reference
+ * inside it — never a local path nor a URL. The type is checked against the allowlist, the
+ * extension and the leading bytes; the total size is capped while reading.
+ */
+export class AttachmentResolver {
+    config;
+    fetchImpl;
+    constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    get configured() {
+        return this.config.sources.length > 0;
+    }
+    sourcesFor(clientId) {
+        return this.config.sources.filter((s) => !s.clients || s.clients.includes(clientId)).map((s) => s.id);
+    }
+    async resolve(clientId, refs) {
+        if (!refs.length)
+            return [];
+        if (!this.configured)
+            throw new EmailError("capability_unavailable", "capability_unavailable: no attachment source is configured (EMAIL_ATTACHMENT_SOURCES) — send without attachments");
+        if (refs.length > this.config.maxCount)
+            throw refused(`${refs.length} attachments, the maximum is ${this.config.maxCount}`);
+        const out = [];
+        let budget = this.config.maxTotalBytes;
+        for (const r of refs) {
+            const a = await this.fetchOne(clientId, r, budget);
+            budget -= a.size;
+            out.push(a);
+        }
+        return out;
+    }
+    async fetchOne(clientId, r, budget) {
+        const src = this.config.sources.find((s) => s.id === r.source && (!s.clients || s.clients.includes(clientId)));
+        if (!src)
+            throw refused(`unknown source "${r.source.slice(0, 40)}" — see email_config for the sources open to this client`);
+        if (r.ref.length > 512 || !REF_RE.test(r.ref))
+            throw refused("the reference must be a relative path of plain segments (no \"..\", no leading \"/\", no URL, no query)");
+        const url = src.baseUrl + r.ref.split("/").map(encodeURIComponent).join("/");
+        if (!url.startsWith(src.baseUrl))
+            throw refused("the reference leaves its source");
+        const name = r.filename ?? r.ref.slice(r.ref.lastIndexOf("/") + 1);
+        if (!FILENAME_RE.test(name))
+            throw refused(`file name "${name.slice(0, 60)}" is not allowed (letters, digits, space . _ ( ) -, 100 characters max)`);
+        const ext = name.includes(".") ? name.slice(name.lastIndexOf(".") + 1).toLowerCase() : "";
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                method: "GET",
+                redirect: "error",
+                headers: { Accept: "*/*", ...(src.authorization ? { Authorization: src.authorization } : {}) },
+                signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            });
+        }
+        catch (err) {
+            throw new EmailError("transient", `transient: attachment ${r.source}:${r.ref} could not be fetched (${redactor.apply(err instanceof Error ? err.message : String(err))})`);
+        }
+        if (res.status === 404)
+            throw new EmailError("not_found", `not_found: attachment ${r.source}:${r.ref} does not exist`);
+        if (res.status === 401 || res.status === 403)
+            throw refused(`source ${r.source} refused access to ${r.ref} (${res.status})`);
+        if (!res.ok)
+            throw new EmailError(res.status >= 500 ? "transient" : "attachment_refused", `${res.status >= 500 ? "transient" : "attachment_refused"}: source ${r.source} answered ${res.status} for ${r.ref}`);
+        const declared = (res.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+        const type = declared && declared !== "application/octet-stream" ? declared : Object.keys(KNOWN_TYPES).find((t) => KNOWN_TYPES[t].exts.includes(ext));
+        if (!type || !this.config.types.includes(type))
+            throw refused(`type ${type ?? "unknown"} is not allowed (allowed: ${this.config.types.join(", ")})`);
+        const spec = KNOWN_TYPES[type];
+        if (!spec.exts.includes(ext))
+            throw refused(`file name "${name}" does not match type ${type} (.${spec.exts.join(", .")})`);
+        const length = Number(res.headers.get("content-length") ?? NaN);
+        if (Number.isFinite(length) && length > budget)
+            throw refused(`${r.ref} is ${length} bytes, above the ${this.config.maxTotalBytes}-byte total (EMAIL_MAX_ATTACHMENT_BYTES)`);
+        const content = await readCapped(res, budget, () => refused(`attachments exceed ${this.config.maxTotalBytes} bytes in total (EMAIL_MAX_ATTACHMENT_BYTES)`));
+        if (!content.length)
+            throw refused(`${r.ref} is empty`);
+        if (spec.magic && !startsWith(content, spec.magic))
+            throw refused(`${r.ref} is not a real ${type} file`);
+        if (spec.text && (content.includes(0) || !isUtf8(content)))
+            throw refused(`${r.ref} is not UTF-8 text`);
+        return { name, type, size: content.length, sha256: createHash("sha256").update(content).digest("hex"), content };
+    }
+}
+function isUtf8(b) {
+    try {
+        new TextDecoder("utf-8", { fatal: true }).decode(b);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readCapped(res, max, tooBig) {
+    if (!res.body)
+        return Buffer.alloc(0);
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > max) {
+            await reader.cancel().catch(() => { });
+            throw tooBig();
+        }
+        chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+}

package/dist/audit.js

@@ -1,7 +1,9 @@
 import { appendFileSync } from "node:fs";
+import { redactor } from "./redact.js";
 /**
  * One JSON object per line on stderr (stdout is the MCP transport) and, optionally, appended to
- * EMAIL_AUDIT_LOG_FILE. Bodies are never logged: the digest is enough to match an entry to its preview.
+ * EMAIL_AUDIT_LOG_FILE. Bodies and attachment contents are never logged: the digest is enough to
+ * match an entry to its preview. Every line goes through the central redactor.
  */
 export class AuditLogger {
     file;
@@ -20,7 +22,7 @@ export class AuditLogger {
             ...rest,
             approvalRef: approvalId ? { id: approvalId, verified: false } : undefined,
         };
-        const line = JSON.stringify(entry);
+        const line = redactor.apply(JSON.stringify(entry));
         this.sink(line);
         if (this.file) {
             try {
@@ -36,32 +38,3 @@ export class AuditLogger {
         return entry;
     }
 }
-/** Sliding one-hour window of sends, per process. */
-export class RateLimiter {
-    maxPerHour;
-    now;
-    sends = [];
-    constructor(maxPerHour, now = Date.now) {
-        this.maxPerHour = maxPerHour;
-        this.now = now;
-    }
-    prune() {
-        const floor = this.now() - 3_600_000;
-        while (this.sends.length && this.sends[0] <= floor)
-            this.sends.shift();
-    }
-    remaining() {
-        this.prune();
-        return Math.max(0, this.maxPerHour - this.sends.length);
-    }
-    /** Takes a slot; returns a function giving it back (for a send that certainly did not leave). */
-    reserve() {
-        const t = this.now();
-        this.sends.push(t);
-        return () => {
-            const i = this.sends.lastIndexOf(t);
-            if (i >= 0)
-                this.sends.splice(i, 1);
-        };
-    }
-}