@aidalinfo/email-mcp 0.1.1 → 0.2.0

package/docs/exploitation.md

@@ -0,0 +1,135 @@
+# 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), 2 Mo au total
+  par défaut, à ajuster à la limite de taille de TEM.

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.2.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"