@aidalinfo/email-mcp 0.1.1 → 0.3.0

package/dist/webhook.js

@@ -0,0 +1,67 @@
+import { UUID_RE } from "./config.js";
+const EVENT_TYPE_RE = /^[a-z_]{1,40}$/;
+export const CONFIRM_TIMEOUT_MS = 10_000;
+/**
+ * Scaleway TEM webhook, delivered through a Topics and Events (SNS) HTTPS subscription.
+ * The subscription URL carries the shared secret; the caller checked it before. Only events of
+ * emails this server sent (known to the ledger) are kept, and only their type and date.
+ */
+export async function handleTemWebhook(body, opts) {
+    let payload;
+    try {
+        payload = JSON.parse(body);
+    }
+    catch {
+        return { status: 400, log: "tem webhook: body is not JSON" };
+    }
+    if (!payload || typeof payload !== "object")
+        return { status: 400, log: "tem webhook: body is not a JSON object" };
+    if (payload.Type === "SubscriptionConfirmation") {
+        // confirm only towards the Scaleway SNS endpoint of the configured region: never an arbitrary URL
+        let url;
+        try {
+            url = new URL(String(payload.SubscribeURL));
+        }
+        catch {
+            return { status: 400, log: "tem webhook: SubscriptionConfirmation without a valid SubscribeURL" };
+        }
+        const expected = `sns.mnq.${opts.region}.scaleway.com`;
+        if (url.protocol !== "https:" || url.hostname !== expected || url.port) {
+            return { status: 400, log: `tem webhook: SubscribeURL host ${url.hostname} refused (expected ${expected})` };
+        }
+        try {
+            const res = await (opts.fetchImpl ?? fetch)(url.href, { method: "GET", redirect: "error", signal: AbortSignal.timeout(CONFIRM_TIMEOUT_MS) });
+            if (!res.ok)
+                return { status: 502, log: `tem webhook: subscription confirmation answered ${res.status}` };
+        }
+        catch (err) {
+            return { status: 502, log: `tem webhook: subscription confirmation failed (${err instanceof Error ? err.name : "error"})` };
+        }
+        return { status: 200, log: "tem webhook: SNS subscription confirmed" };
+    }
+    let event = payload;
+    if (payload.Type === "Notification") {
+        try {
+            event = JSON.parse(String(payload.Message));
+        }
+        catch {
+            return { status: 400, log: "tem webhook: Notification whose Message is not JSON" };
+        }
+    }
+    else if (payload.Type !== undefined) {
+        return { status: 202, log: `tem webhook: SNS message type ignored` };
+    }
+    const type = event?.type;
+    const emailId = typeof event?.email_id === "string" ? event.email_id.toLowerCase() : undefined;
+    if (typeof type !== "string" || !EVENT_TYPE_RE.test(type))
+        return { status: 400, log: "tem webhook: event without a valid type" };
+    if (event.project_id !== undefined && String(event.project_id).toLowerCase() !== opts.projectId) {
+        return { status: 202, log: "tem webhook: event of another project ignored" };
+    }
+    if (!emailId || !UUID_RE.test(emailId))
+        return { status: 202, log: `tem webhook: ${type} without email id ignored` };
+    const created = typeof event.created_at === "string" ? Date.parse(event.created_at) : NaN;
+    const at = new Date(Number.isFinite(created) ? created : (opts.now ?? Date.now)()).toISOString();
+    const kept = opts.ledger.addEvent(emailId, { type, at });
+    return kept ? { status: 204, log: `tem webhook: ${type} recorded for ${emailId}` } : { status: 202, log: `tem webhook: ${type} for an email not sent by this server ignored` };
+}

package/docs/exploitation.md

@@ -0,0 +1,140 @@
+# Exploitation du MCP email central
+
+Serveur `@aidalinfo/email-mcp` en mode HTTP (`EMAIL_MCP_TRANSPORT=http`), partagé par les agents
+Hermes. Ce document couvre le déploiement, les clés clientes, le coupe-circuit, le webhook Scaleway
+TEM et la recette **sans envoi réel**.
+
+> Chaque étape qui touche l'infrastructure (identité IAM Scaleway, application Coolify, DNS,
+> Traefik, premier envoi réel) demande une **validation humaine séparée** avant exécution
+> (issue #67, « hors périmètre »). Ce document décrit le « comment », il n'autorise rien.
+
+## 1. Prérequis Scaleway
+
+1. Domaine `pulsemyit.fr` en statut **`checked`** dans Transactional Email (projet et région choisis).
+2. **Application IAM dédiée** `email-mcp`, politique `TransactionalEmailFullAccess` limitée **à ce
+   seul projet**, une clé API. Elle n'est déposée que dans l'environnement du serveur (Coolify,
+   variable marquée secrète) — jamais dans la configuration d'un agent.
+
+## 2. Déploiement (Coolify)
+
+- **Serveur** : un worker Coolify, **jamais** l'hôte de management / routage.
+- **Image** : `docker build -f packages/email-mcp/Dockerfile -t email-mcp:<version> .` depuis la
+  racine du dépôt. Rien n'est téléchargé au démarrage ; l'image tourne en utilisateur `node`.
+- **Compose** : [`deploy/compose.yaml`](../deploy/compose.yaml) — système de fichiers en lecture
+  seule, `cap_drop: ALL`, `no-new-privileges`, volume `/data` (registre des envois, audit,
+  coupe-circuit), `/config` en lecture seule (`clients.json`, `templates/`).
+- **Variables obligatoires** : `SCW_SECRET_KEY`, `EMAIL_PROJECT_ID`, `EMAIL_ALLOWED_RECIPIENTS`, et
+  un fichier clients valide. Il en manque une → le conteneur s'arrête avec un message explicite
+  (`Missing required env var: …`, `Missing client keys: …`) et ne répond pas. L'expéditeur est fixé
+  à `noreply@pulsemyit.fr` dans l'image.
+- **Santé** : `GET /health` → `{"status":"ok","service":"email-mcp","version":"…","sending":"enabled|disabled"}`.
+  Aucun secret, aucun identifiant de projet, aucune région.
+
+### Exposition publique
+
+Tant que l'enregistrement DNS `email.mcp.pulsemyit.fr` n'est **pas créé et validé**, ne déclarez
+**aucun domaine** sur l'application Coolify : le service reste joignable seulement sur le réseau
+interne (`expose: 8080`, pas de `ports:`). Une fois le DNS validé (décision séparée) : domaine
+`https://email.mcp.pulsemyit.fr` dans Coolify, certificat TLS par Traefik, puis recette (§ 6).
+
+## 3. Clés clientes
+
+Une clé par agent (`emk_` + 256 bits aléatoires). Le serveur ne garde que son **empreinte SHA-256**.
+
+```bash
+npx -y @aidalinfo/email-mcp keygen hermes-ops
+# client key (give it to "hermes-ops" only, it is not stored anywhere):
+# emk_…
+# clients file entry:
+# {"id":"hermes-ops","keys":["sha256:…"]}
+```
+
+1. Ajoutez l'entrée dans `/config/clients.json` (voir [`deploy/clients.example.json`](../deploy/clients.example.json)) :
+   `maxPerHour`, `maxPerDay` (ne peuvent que baisser les limites du serveur), `allowedRecipients`
+   (restreint l'allowlist du serveur), `templatesOnly` (routines), `disabled`.
+2. Déposez la clé dans le coffre de l'agent (secret Hermes), jamais dans un dépôt, un ticket ou un
+   message.
+3. Le fichier est relu à chaque modification : **pas de redémarrage**. S'il devient invalide (JSON
+   cassé, clé brute au lieu d'une empreinte…), **toutes** les requêtes sont refusées jusqu'à
+   correction, et un avertissement part sur stderr.
+
+### Rotation sans coupure
+
+1. `keygen` pour le même client → ajoutez la nouvelle empreinte **à côté** de l'ancienne (`"keys": [ancienne, nouvelle]`).
+2. Mettez la nouvelle clé dans le coffre de l'agent, vérifiez un appel (`email_config`).
+3. Retirez l'ancienne empreinte du fichier.
+
+### Révocation
+
+Retirez l'empreinte (ou passez `"disabled": true`) : effet à la requête suivante. Une clé
+compromise se révoque **avant** d'en émettre une nouvelle.
+
+## 4. Coupe-circuit
+
+```bash
+docker exec <conteneur> touch /data/STOP   # tout envoi est refusé immédiatement (aperçu et envoi)
+docker exec <conteneur> rm /data/STOP      # reprise
+```
+
+`/health` passe à `"sending":"disabled"`. Pour un seul agent : `"disabled": true` dans `clients.json`.
+
+## 5. Webhook Scaleway TEM (suivi des livraisons)
+
+TEM publie ses événements dans un **topic Topics and Events (SNS)** ; le serveur s'y abonne en HTTPS.
+
+1. `EMAIL_WEBHOOK_SECRET=$(openssl rand -hex 32)` dans l'environnement du serveur.
+2. Topics and Events : créer un topic dans la région du domaine, puis un **abonnement HTTPS** vers
+   `https://email.mcp.pulsemyit.fr/webhooks/tem/<EMAIL_WEBHOOK_SECRET>`. Le serveur confirme lui-même
+   l'abonnement, **uniquement** si l'URL de confirmation est `https://sns.mnq.<région>.scaleway.com/…`.
+3. Transactional Email → Webhooks : créer un webhook sur le domaine, avec l'ARN du topic et les
+   types `email_delivered`, `email_dropped`, `email_deferred`, `email_spam`,
+   `email_mailbox_not_found`, `email_blocklisted`.
+
+Ce qui est gardé : le **type** et la **date** de l'événement, et seulement pour les e-mails envoyés
+par ce serveur (connus du registre). Les événements d'un autre projet ou d'un autre e-mail sont
+ignorés (202). Mauvais secret → 404. Les agents les lisent dans `email_status` (`deliveryEvents`).
+Les suppressions (rebond dur, plainte) se lisent avec `email_suppressions` (adresses autorisées seulement).
+
+Sans webhook, `email_status` l'indique (`"deliveryEvents": "webhook not configured"`) au lieu de
+renvoyer une liste vide ambiguë.
+
+## 6. Recette sans envoi réel
+
+1. **Démarrage en échec** : lancer l'image sans `SCW_SECRET_KEY` → sortie immédiate avec
+   `Missing required env var: SCW_SECRET_KEY`. Sans fichier clients → `Missing client keys`.
+2. **Contrôle de déploiement** (aucun envoi : seul un aperçu est demandé, son jeton est jeté) :
+
+   ```bash
+   EMAIL_MCP_URL=https://email.mcp.pulsemyit.fr \
+   EMAIL_MCP_KEY=emk_…  EMAIL_MCP_CHECK_TO=vous@pulsemyit.fr \
+     node packages/email-mcp/scripts/deploy-check.mjs
+   ```
+
+   Vérifie `/health` (et qu'il ne révèle rien), le refus sans clé et avec une mauvaise clé (401),
+   `initialize`, `tools/list`, `email_config` et un `email_preview` dont l'expéditeur effectif est
+   `noreply@pulsemyit.fr`.
+3. **Deux clients** : refaire 2. avec la clé d'un second agent ; dans le journal d'audit, chaque
+   entrée porte son `client`.
+4. **Coupe-circuit** : `touch /data/STOP`, refaire 2. → l'aperçu est refusé (`kill switch`) ; `rm`.
+5. Le **premier envoi réel** (allowlist réduite à une adresse de l'équipe) est une décision séparée.
+
+## 7. Journal d'audit
+
+Une ligne JSON par aperçu, envoi, rejeu, refus ou échec, sur stderr et dans `EMAIL_AUDIT_LOG_FILE`
+(`/data/audit.jsonl`, mode 600) : `timestamp`, `tool`, `client`, `result`, `from`, `to`, `cc`,
+`subject`, `messageDigest`, `template`, `attachments` (type, taille, sha256), `temEmailIds`,
+`idempotencyKey`, `errorCode`, `approvalRef`. **Jamais** de corps, de contenu ni de nom de pièce
+jointe, de clé cliente ou de secret ; chaque ligne passe par le masquage central. Les refus
+d'authentification sont journalisés (`tool: "http"`, `errorCode: "unauthorized"`) sans la clé reçue.
+
+## 8. Limites connues
+
+- Quotas en mémoire : un redémarrage les remet à zéro (le registre empêche toujours les doublons).
+- Une seule instance : le registre est un fichier local, pas de réplication.
+- Pièces jointes : jointes au message (pas de lien de téléchargement temporaire). L'API TEM refuse
+  tout e-mail de plus de 2 Mo (non augmentable) : au-delà, le serveur passe par le SMTP de TEM
+  (`EMAIL_SEND_VIA=auto`, port sortant 2465 à ouvrir), limité à 50 Mo par e-mail, soit 35 Mo de
+  pièces jointes par défaut. Avec `EMAIL_SEND_VIA=api`, la limite reste 2 Mo.
+- Envois SMTP : pas d'identifiant TEM au moment de l'envoi. `email_status` (par
+  `idempotency_key`) les retrouve quand TEM liste l'e-mail ; les événements webhook reçus avant
+  ne sont pas rattachés.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aidalinfo/email-mcp",
-  "version": "0.1.1",
-  "description": "Outbound email MCP server over Scaleway Transactional Email (TEM) — fixed sender from config, recipient allowlist, two-step confirmed, rate-limited and audited sends",
+  "version": "0.3.0",
+  "description": "Outbound email MCP server over Scaleway Transactional Email (TEM) — stdio or central Streamable HTTP with per-client Bearer keys, fixed sender, recipient allowlist, preview then confirmed idempotent sends, quotas, kill switch, versioned templates, controlled attachments, delivery webhook and audit",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -9,7 +9,9 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "docs",
+    "deploy"
   ],
   "publishConfig": {
     "access": "public"
@@ -42,11 +44,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0",
+    "nodemailer": "^10.5.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@jest/globals": "^30.3.0",
     "@types/node": "^26.6.5",
+    "@types/nodemailer": "^8.0.2",
     "jest": "^30.3.0",
     "ts-jest": "^29.4.6",
     "typescript": "^5.7.0"