SPB Git

Repository Public

README.md 51.6 KB 678 lines markdown

1<div align="center">23<img src="docs/brand/logo.svg" alt="SP Mail logo" width="560">45<br><br>67<img src="docs/brand/icon.png" alt="SP Mail icon" width="112" height="112">89# SP Mail1011**Messagerie personnelle auto-hébergée pour `spboucher.ai` : serveur de courrier Stalwart (envoi et réception directs, sans relais tiers), backend à clés d'accès (passkeys) avec passerelle JMAP, webmail React, API REST `/api/v1` à clés et portées, studio de modèles avec génération par IA, serveur MCP et SDK.**1213**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**1415[![mail.spboucher.ai](https://img.shields.io/website?url=https%3A%2F%2Fmail.spboucher.ai%2Fapi%2Fhealth%2Flive&label=mail.spboucher.ai&style=for-the-badge&up_message=en%20ligne&down_message=hors%20ligne)](https://mail.spboucher.ai)16![version](https://img.shields.io/badge/version-0.3.0-blue?style=for-the-badge)17![plateforme](https://img.shields.io/badge/plateforme-web%20%C2%B7%20API%20%C2%B7%20MCP-2c5b4d?style=for-the-badge)18![langues](https://img.shields.io/badge/langues-FR%20%C2%B7%20EN-8A2BE2?style=for-the-badge)19![licence](https://img.shields.io/badge/licence-UNLICENSED%20%C2%B7%20tous%20droits%20r%C3%A9serv%C3%A9s-lightgrey?style=for-the-badge)20![author](https://img.shields.io/badge/author-Simon--Pierre%20Boucher-0A66C2?style=for-the-badge)2122![Stalwart](https://img.shields.io/badge/Stalwart-1.1.1%20%C3%A9pingl%C3%A9-DB2B39?style=flat-square)23![Fastify](https://img.shields.io/badge/Fastify-5.12-000000?style=flat-square&logo=fastify&logoColor=white)24![React](https://img.shields.io/badge/React-19.3-20232A?style=flat-square&logo=react&logoColor=white)25![TypeScript](https://img.shields.io/badge/TypeScript-7.0-3178C6?style=flat-square&logo=typescript&logoColor=white)26![Vite](https://img.shields.io/badge/Vite-8.3-646CFF?style=flat-square&logo=vite&logoColor=white)27![PostgreSQL](https://img.shields.io/badge/PostgreSQL-17-4169E1?style=flat-square&logo=postgresql&logoColor=white)28![postgres.js](https://img.shields.io/badge/postgres.js-4.1-336791?style=flat-square)29![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A5%2022-5FA04E?style=flat-square&logo=nodedotjs&logoColor=white)30![WebAuthn](https://img.shields.io/badge/WebAuthn-SimpleWebAuthn%2014-3423A6?style=flat-square&logo=webauthn&logoColor=white)31![Zod](https://img.shields.io/badge/Zod-4.6-3E67B1?style=flat-square&logo=zod&logoColor=white)32![DOMPurify](https://img.shields.io/badge/DOMPurify-3.2-663399?style=flat-square)33![parse5](https://img.shields.io/badge/parse5-8.1-informational?style=flat-square)34![Anthropic SDK](https://img.shields.io/badge/%40anthropic--ai%2Fsdk-1.10-D97757?style=flat-square&logo=anthropic&logoColor=white)35![OpenAPI](https://img.shields.io/badge/OpenAPI-3.1.0-6BA539?style=flat-square&logo=openapiinitiative&logoColor=white)36![MCP](https://img.shields.io/badge/MCP%20SDK-1.20-000000?style=flat-square)37![esbuild](https://img.shields.io/badge/esbuild-0.28-FFCF00?style=flat-square&logo=esbuild&logoColor=black)38![Playwright](https://img.shields.io/badge/Playwright-1.65-2EAD33?style=flat-square&logo=playwright&logoColor=white)39![axe-core](https://img.shields.io/badge/axe--core-4.14-663399?style=flat-square)40![pnpm](https://img.shields.io/badge/pnpm-lockfile-F69220?style=flat-square&logo=pnpm&logoColor=white)41![ClamAV](https://img.shields.io/badge/ClamAV-milter-C8102E?style=flat-square)4243[![commits](https://git.spboucher.ai/badge/sp-mail/commits.svg?style=flat-square)](https://git.spboucher.ai/sp-mail/commits)44[![last commit](https://git.spboucher.ai/badge/sp-mail/last-commit.svg?style=flat-square)](https://git.spboucher.ai/sp-mail/commits)45[![activity](https://git.spboucher.ai/badge/sp-mail/activity.svg?style=flat-square)](https://git.spboucher.ai/sp-mail/insights)46[![language](https://git.spboucher.ai/badge/sp-mail/language.svg?style=flat-square)](https://git.spboucher.ai/sp-mail)47[![languages](https://git.spboucher.ai/badge/sp-mail/languages.svg?style=flat-square)](https://git.spboucher.ai/sp-mail/insights)48[![size](https://git.spboucher.ai/badge/sp-mail/size.svg?style=flat-square)](https://git.spboucher.ai/sp-mail)49[![branches](https://git.spboucher.ai/badge/sp-mail/branches.svg?style=flat-square)](https://git.spboucher.ai/sp-mail/branches)50[![tags](https://git.spboucher.ai/badge/sp-mail/tags.svg?style=flat-square)](https://git.spboucher.ai/sp-mail/tags)51[![clones](https://git.spboucher.ai/badge/sp-mail/clones.svg?style=flat-square)](https://git.spboucher.ai/sp-mail)5253![routes API v1](https://img.shields.io/badge/routes%20%2Fapi%2Fv1-54-blue?style=flat-square)54![routes session et admin](https://img.shields.io/badge/routes%20session%20%2B%20admin-70-blue?style=flat-square)55![tables](https://img.shields.io/badge/tables%20PostgreSQL-28-blue?style=flat-square)56![migrations](https://img.shields.io/badge/migrations-3-blue?style=flat-square)57![portées](https://img.shields.io/badge/port%C3%A9es%20d%27API-13-blue?style=flat-square)58![outils MCP](https://img.shields.io/badge/outils%20MCP-17-blue?style=flat-square)59![SDK](https://img.shields.io/badge/SDK-TypeScript%20%C2%B7%20Python%20%C2%B7%20Swift-blue?style=flat-square)60![tests d'intégration](https://img.shields.io/badge/tests%20d%27int%C3%A9gration-67-brightgreen?style=flat-square)61![tests webmail](https://img.shields.io/badge/tests%20webmail-177-brightgreen?style=flat-square)62![scénarios e2e](https://img.shields.io/badge/sc%C3%A9narios%20e2e-85-brightgreen?style=flat-square)63![tests SDK et MCP](https://img.shields.io/badge/tests%20SDK%20%2B%20MCP-31-brightgreen?style=flat-square)64![accessibilité](https://img.shields.io/badge/accessibilit%C3%A9-axe%20%C2%B7%200%20grave-brightgreen?style=flat-square)65![fichiers TypeScript](https://img.shields.io/badge/fichiers%20TypeScript-253-informational?style=flat-square)66![lignes TypeScript](https://img.shields.io/badge/lignes%20TypeScript-48%20344-informational?style=flat-square)6768![nœud](https://img.shields.io/badge/n%C5%93ud-M4M64c-8A2BE2?style=flat-square)69![port](https://img.shields.io/badge/port-8730-informational?style=flat-square)70![PM2](https://img.shields.io/badge/PM2-sp--mail%20%C2%B7%20sp--mail--backup%20%C2%B7%20sp--mail--edge--pull-2B037A?style=flat-square&logo=pm2&logoColor=white)71![serveur de courrier](https://img.shields.io/badge/courrier-BHS64%20%C2%B7%20mx1.spboucher.ai%3A25-DB2B39?style=flat-square)72![déploiement](https://img.shields.io/badge/d%C3%A9ploiement-mld-orange?style=flat-square)73![tunnel](https://img.shields.io/badge/tunnel-MacLustr%20Tunnel%20%C2%B7%20Caddy%20%2B%20WireGuard-1F8B4C?style=flat-square&logo=wireguard&logoColor=white)7475</div>7677---7879## Sommaire8081- [Vue d'ensemble](#-vue-densemble)82- [Fonctionnalités](#-fonctionnalités)83- [Architecture](#-architecture)84- [Pile technique](#-pile-technique)85- [Arborescence](#-arborescence)86- [Développer](#-développer)87- [Configuration](#-configuration)88- [API](#-api)89- [Modèle de données](#-modèle-de-données)90- [Intégrations : clés, SDK, MCP, webhooks](#-intégrations--clés-sdk-mcp-webhooks)91- [Sécurité et vie privée](#-sécurité-et-vie-privée)92- [Tester](#-tester)93- [Déployer, sauvegarder, restaurer, mettre à jour](#-déployer-sauvegarder-restaurer-mettre-à-jour)94- [Pièges et comportements à connaître](#-pièges-et-comportements-à-connaître)95- [Limites connues et non fait](#-limites-connues-et-non-fait)96- [Documentation](#-documentation)97- [Auteur](#-auteur)98- [Licence](#-licence)99100---101102## 🚀 SP Mail Next (branche `next`)103104Évolution majeure en cours de livraison — **non déployée** : la production reste en 0.3.0 tant que `docs/next/RELEASE-NEXT.md` n'a pas été exécuté.105106| Document | Contenu |107|---|---|108| [`docs/next/AUDIT-NEXT.md`](docs/next/AUDIT-NEXT.md) | état réel du code avant le chantier, défauts trouvés |109| [`docs/next/ARCHITECTURE-NEXT.md`](docs/next/ARCHITECTURE-NEXT.md) | décisions et contrat `/api/next` |110| [`docs/next/DESIGN-SYSTEM-NEXT.md`](docs/next/DESIGN-SYSTEM-NEXT.md) | système de design (clair, sombre, minuit) |111| [`docs/next/IMPLEMENTATION-PLAN.md`](docs/next/IMPLEMENTATION-PLAN.md) | phases et priorités |112| [`docs/next/FEATURE-PARITY.md`](docs/next/FEATURE-PARITY.md) | parité web · macOS · iOS · iPadOS, avec ce qui est testé ou seulement compilé |113| [`docs/next/TEST-REPORT-NEXT.md`](docs/next/TEST-REPORT-NEXT.md) | essais exécutés et preuves, non testé déclaré |114| [`docs/next/RELEASE-NEXT.md`](docs/next/RELEASE-NEXT.md) | mise en production et retour arrière |115| [`PUSH`](docs/next/PUSH.md) · [`SEARCH`](docs/next/SEARCH.md) · [`INTELLIGENCE`](docs/next/INTELLIGENCE.md) · [`OPERATIONS-NEXT`](docs/next/OPERATIONS-NEXT.md) · [`PERFORMANCE`](docs/next/PERFORMANCE.md) | références par domaine |116117Ajouts principaux : notifications push APNs (file durable, préférences, heures calmes), mise en veille et rappels côté serveur, libellés, recherches enregistrées, extraits, signatures multiples, contacts, recherche unifiée à opérateurs, galerie de pièces jointes, annulation d'envoi par retenue côté serveur, centre de commande, couche d'intelligence **optionnelle et désactivée par défaut** (fournisseur local ou externe avec consentement explicite), règles d'automatisation, santé et alertes d'exploitation, webmail redessiné (volets redimensionnables, palette de commandes, rédaction riche, hors ligne), migrations `004`–`007` purement additives.118119## 🎯 Vue d'ensemble120121SP Mail est la messagerie du domaine `spboucher.ai`, entièrement auto-hébergée :122123- **le courrier arrive et part directement** par un serveur Stalwart (`mx1.spboucher.ai`, port 25), sans relais tiers ; le MX du domaine a été basculé le 2026-11-19 (8 boîtes, 20 alias — `docs/test-report.md`, M1–M3) ;124- **aucun mot de passe** : l'identité repose sur des clés d'accès WebAuthn (passkeys), avec une session révocable par appareil ;125- **les clients ne parlent jamais au serveur de courrier** : web, macOS et iOS parlent JMAP standard (RFC 8620/8621) à une passerelle du backend, qui ajoute le secret scellé de la boîte ;126- **les applications et les agents IA** passent par une API REST `/api/v1` à clés, portées et listes d'adresses, avec approbation des envois externes, webhooks signés, SDK et serveur MCP ;127- **rien n'est simulé** : les tests tournent contre un vrai PostgreSQL et le vrai Stalwart (domaine de recette `stg.spboucher.ai`), et `docs/test-report.md` marque honnêtement ce qui est PASS, BLOCKED ou NON FAIT.128129### Famille SP Mail130131| Élément | Dépôt spbgit | Rôle |132|---|---|---|133| Backend + webmail + API + MCP + SDK | **[sp-mail](https://git.spboucher.ai/sp-mail)** (ce dépôt) | `https://mail.spboucher.ai` |134| Apps natives macOS et iOS/iPadOS | [sp-mail-apple](https://git.spboucher.ai/sp-mail-apple) (copie de travail : `~/Desktop/Cluster/apple/SPMail`) | SwiftUI, socle `SPMailCore`, hors ligne, mêmes routes |135136Versions : la production annonce **0.3.0** (`/api/v1/health`, `docs/test-report.md` V7) ; la version servie vient de la variable `SPMAIL_VERSION` (le champ `version` de `package.json` est resté à `0.1.0`). Le contrat `/api/v1` est en `1.0.0` (`docs/OPENAPI.yaml`), comme les SDK TypeScript et Python et le serveur MCP.137138## ✨ Fonctionnalités139140| Domaine | Ce que fait le code |141|---|---|142| **Serveur de courrier** | Stalwart 1.1.1 épinglé : SMTP direct en STARTTLS, DKIM double (ed25519 + RSA-2048), vérifications SPF/DKIM/DMARC/iprev entrantes, antispam (score ≥ 5 → Indésirables, jamais de suppression silencieuse), ClamAV en milter (550 si infecté, 4xx si l'antivirus est en panne), pas de catch-all, pas de relais ouvert |143| **Identité** | passkeys seulement (identifiant découvrable, vérification de l'utilisateur exigée) ; enrôlement par lien à usage unique émis par le CLI ; sessions web (cookie `__Host-`) et natives (jeton porteur) révocables par appareil ; ré-authentification passkey de 5 min pour les opérations sensibles |144| **Passerelle JMAP** | `Mailbox`, `Email`, `Thread`, `EmailSubmission`, `Identity`, `SieveScript`, `VacationResponse`, blobs, quota, contacts, calendriers ; EventSource relayé (états seulement) ; capacité `urn:stalwart:jmap` et méthodes `x:*` refusées |145| **Webmail** | liste fenêtrée (10 000 messages, < 60 lignes dans le DOM), lecture dans un cadre isolé sans scripts, contenu distant bloqué par défaut puis servi par le mandataire `/api/img`, rédaction avec pièces jointes, fils, recherche, drapeaux, actions annulables, raccourcis clavier, brouillons conservés, cache IndexedDB, FR/EN, bureau + mobile |146| **Boîte unifiée** | « Toutes les boîtes » : liste paginée sur plusieurs boîtes, pastilles par boîte, arrivée en direct |147| **Identités d'expédition** | envoi depuis une boîte ou un alias, `From` construit par le serveur, signature qui suit l'identité |148| **Réglages** | identités et signatures, filtres Sieve, réponse automatique, sécurité (passkeys, appareils), export `.eml` / mbox / ZIP |149| **Studio de modèles** | bibliothèque, éditeur de code, variables `{{nom}}`, versions (50 dernières, restauration), aperçu clair/sombre isolé, génération et retouche par IA en flux SSE (`claude-opus-5-5` par défaut), envoi réel d'un modèle, panneau cURL |150| **API `/api/v1`** | envoi (simple, lot, réponse, transfert, programmé), lecture, recherche, synchronisation incrémentale, brouillons, fichiers, adresses et alias, automatisation, webhooks, événements, idempotence, pagination par curseur opaque |151| **Adresses** | 7 genres (`mailbox`, `shared`, `alias`, `notification`, `send_only`, `receive_only`, `temporary`), suspension appliquée sur le serveur de courrier, expiration, adresses protégées, alias à destinations multiples, droits partagés (`mailbox_grants`) |152| **Console d'administration** | vue d'ensemble, boîtes, adresses, DNS en direct (MX, SPF, DKIM, DMARC, PTR), file d'attente, clés d'API (assistant, usage, rotation), approbations, webhooks (livraisons, rejeu, liste d'autorisation interne), automatisation (règles, réponse automatique, programmés), infrastructure (santé, métriques, stockage, graphiques SVG), API Explorer (OpenAPI → formulaire, jeton jamais affiché), audit |153| **Travailleurs** | en processus : envois programmés et suivi de remise, veilleur de réception (interrogation toutes les 5 s), livraisons de webhooks avec reprise, expiration des adresses temporaires, conservation ; reprise après redémarrage |154| **Agents IA** | serveur MCP stdio (17 outils), contenu des courriels rendu comme donnée non fiable, mode lecture seule |155| **Exploitation** | CLI d'exploitation (14 commandes), sauvegardes chiffrées du courrier et de la base, test de restauration sur une seconde instance, surveillance |156157## 🏗 Architecture158159```mermaid160flowchart LR161  subgraph Internet162    MTA[Serveurs de courrier tiers]163    U[Navigateur · app macOS · app iOS]164    APP[Applications · agents IA<br/>clé spm_… · SDK · MCP]165  end166  subgraph BHS64["Passerelle BHS64 — OVH Beauharnois"]167    direction TB168    S25["Stalwart 1.1.1<br/>SMTP :25 public · mx1.spboucher.ai"]169    SJ["Stalwart JMAP + gestion<br/>:8080 privé (loopback + WireGuard)"]170    DB[("RocksDB<br/>boîtes, index, file d'attente")]171    AV["ClamAV milter"]172    C["Caddy :443<br/>mail.spboucher.ai"]173    BK["Sauvegarde chiffrée 03:20"]174  end175  subgraph MacLustr["MacLustr — nœud M4M64c"]176    API["Backend SP Mail :8730<br/>passkeys · sessions · passerelle JMAP<br/>API v1 · admin · travailleurs"]177    PG[("PostgreSQL 17 · sp_mail<br/>identités, clés, files, secrets scellés")]178    BK2["Copie des sauvegardes 03:50"]179  end180  AI["API Anthropic<br/>génération de modèles"]181  MTA <-- "SMTP + STARTTLS" --> S25182  S25 --- DB183  SJ --- DB184  S25 -- scan --> AV185  U -- HTTPS --> C186  APP -- HTTPS --> C187  C -- WireGuard --> API188  API -- "JMAP (WireGuard, secret par boîte)" --> SJ189  API --- PG190  API -. "brief + marque seulement" .-> AI191  BK -- "clé SSH à commande forcée" --> BK2192```193194| Zone | Contenu | Exposition |195|---|---|---|196| **Bordure publique** (BHS64) | Stalwart : réception/envoi SMTP direct, DKIM, SPF/DMARC/iprev entrants, antispam, file d'attente, **stockage des boîtes** ; ClamAV ; Caddy | 25/tcp (SMTP) et 443/tcp (Caddy). Pas d'IMAP, pas de submission, pas de console d'administration publics |197| **Gestion du serveur de courrier** | API JMAP + gestion de Stalwart (`:8080`, HTTP clair) | loopback et interface WireGuard ; `ufw` n'accepte que l'adresse du backend |198| **Backend** (M4M64c) | identité, sessions par appareil, passerelle JMAP, API `/api/v1`, administration, mandataire d'images, travailleurs | derrière Caddy (`mail.spboucher.ai`), joint par WireGuard |199| **Clients** | web (React/TS), macOS et iOS (SwiftUI, socle `SPMailCore`) | parlent JMAP standard **au backend**, jamais à Stalwart |200201**Pourquoi une passerelle plutôt que Stalwart exposé directement** : une seule surface d'authentification (passkeys), des sessions révocables par appareil, aucun mot de passe de boîte dans un client, et la console de gestion hors d'Internet. Chaque boîte a dans Stalwart un mot de passe aléatoire que personne ne connaît ; le backend le garde scellé (AES-256-GCM, clé maîtresse hors base) et l'ajoute aux requêtes relayées.202203### Connexion par clé d'accès puis lecture204205```mermaid206sequenceDiagram207    autonumber208    participant C as Client (web / natif)209    participant B as Backend SP Mail210    participant P as PostgreSQL211    participant S as Stalwart (JMAP)212    C->>B: POST /api/login/options213    B->>P: enregistre le défi214    B-->>C: challenge_id + options WebAuthn215    C->>C: Touch ID / Face ID signe le défi216    C->>B: POST /api/login/verify {challenge_id, response, client}217    B->>P: vérifie la signature, crée la session (SHA-256 du jeton)218    B-->>C: cookie __Host-spmail_session (web) ou jeton porteur (natif)219    C->>B: GET /api/me220    B-->>C: utilisateur, session, boîtes221    C->>B: POST /api/jmap/{boîte}/api {using, methodCalls}222    B->>P: résout (boîte, utilisateur de la session), descelle le secret223    B->>S: requête JMAP relayée par WireGuard224    S-->>B: réponses225    B-->>C: réponses (URL réécrites vers la passerelle)226```227228### Envoi par l'API avec garde des destinataires externes229230```mermaid231sequenceDiagram232    autonumber233    participant A as Application (clé spm_…)234    participant B as /api/v1235    participant W as Travailleur d'envoi236    participant S as Stalwart237    participant H as Webhook de l'application238    A->>B: POST /messages/send + Idempotency-Key239    B->>B: portée mail.send, adresse autorisée, plafonds240    alt destinataire externe et politique approval241        B-->>A: 202 pending_approval (rien n'est parti)242        Note over B: un administrateur approuve ou rejette (ré-authentification passkey)243    else interne ou politique allow244        B-->>A: msg_out_… (queued / sent)245    end246    W->>S: Email/set + EmailSubmission/set247    S-->>W: deliveryStatus par destinataire248    W->>H: message.sent / delivered / bounced (signé)249```250251### Flux du courrier252253- **Réception** : MTA tiers → `mx1.spboucher.ai:25` (STARTTLS, certificat Let's Encrypt obtenu par Caddy et recopié vers Stalwart par `sp-mail-cert.path`) → SPF/DKIM/DMARC/iprev → ClamAV → antispam → boîte.254- **Envoi** : client → `EmailSubmission/set` (passerelle) → file Stalwart → signature DKIM → livraison directe au MX du destinataire, **IPv4 seulement** (pas de PTR IPv6). Aucun relais tiers.255- **Lecture** : client → `https://mail.spboucher.ai/api/jmap/{boîte}/…` → backend → Stalwart.256- **Temps réel** : EventSource JMAP relayé (états seulement, jamais de contenu). Push iOS (APNs) : prévu, non émis.257258<details>259<summary>Choix écartés (docs/architecture.md)</summary>260261| Écarté | Raison |262|---|---|263| Boîtes stockées sur MacLustr, BHS64 simple relais | deux Stalwart à maintenir ; lecture dépendante du réseau résidentiel. Réversible : export/import Stalwart |264| IMAP / submission publics | inutiles aux trois clients SP Mail ; surface d'attaque et mots de passe d'application en plus. Ouvrables plus tard |265| ACME intégré de Stalwart | Caddy possède déjà 80/443 sur BHS64 |266| IPv6 pour SMTP | pas de PTR IPv6 ; Gmail rejette sans PTR |267| IA dans le chemin de livraison | l'IA est un service séparé, optionnel, jamais requis |268269</details>270271## 🧱 Pile technique272273| Couche | Technologie | Version (lue dans le dépôt) | Rôle |274|---|---|---|---|275| Serveur de courrier | Stalwart + `stalwart-cli` | 1.1.1 (épinglé) · 2.0.0 | SMTP, JMAP, DKIM, antispam, stockage RocksDB |276| Antivirus | ClamAV + milter | paquet système | analyse à l'étape DATA |277| Backend | Fastify · `@fastify/cookie` · `@fastify/static` | ^5.12.8 · ^11.1.5 · ^10.1.11 | HTTP, sessions, service du build web |278| Identité | `@simplewebauthn/server` · `/browser` | ^14.1.0 · ^14.0.0 | WebAuthn |279| Base | PostgreSQL · `postgres` | 17 · ^4.1.1 | identités, clés, files, modèles |280| Validation | Zod | ^4.6.7 | schémas des routes → OpenAPI 3.1 |281| Assainissement | DOMPurify · parse5 | ^3.2.6 · ^8.1.1 | HTML des messages (web) et des modèles (serveur) |282| IA | `@anthropic-ai/sdk` | ^1.10.0 | génération de modèles (optionnelle) |283| Webmail | React · react-dom | ^19.3.1 | SPA, aucun cadriciel CSS, polices système |284| Outillage | TypeScript · Vite · esbuild · tsx | ^7.0.2 · ^8.3.8 · ^0.28.2 · ^4.23.15 | typage, build web, bundles `dist/server.mjs` et `dist/cli.mjs` |285| Tests | `node:test` · jsdom · Playwright · axe | — · ^31.0.1 · ^1.65.1 · ^4.14.0 | intégration, logique, e2e, accessibilité |286| MCP | `@modelcontextprotocol/sdk` | ^1.20.0 | serveur d'outils pour agents |287| SDK | TypeScript `@spboucher/spmail` 1.0.0 · Python `spmail` 1.0.0 (≥ 3.10) · Swift `SPMailClient` (tools 6.0) | — | clients de `/api/v1` |288| Exécution | Node.js | ≥ 22 | `engines` |289290## 🗂 Arborescence291292```293server/src/            backend Fastify (40 fichiers, 5 629 lignes)294  index.ts             démarrage et assemblage des routes295  auth.ts session.ts   passkeys, enrôlement, sessions par appareil ; reauth.ts : ré-authentification296  jmap.ts mailjmap.ts  passerelle JMAP ; stalwart.ts : gestion du serveur de courrier297  admin.ts adminapi.ts administration (boîtes, DNS, file, clés, approbations, métriques)298  keys.ts              clés d'API, portées, plafonds ; addresses.ts sieve.ts : adresses, automatisation299  images.ts            mandataire d'images anti-SSRF ; sanitize.ts template-sanitize.ts300  templates.ts templates-ai.ts   studio de modèles et génération301  outbound.ts webhooks.ts        suivi d'envoi, webhooks302  v1/                  API REST : registry.ts (une définition = validation + OpenAPI), send, messages,303                       addresses, templates, webhooks, meta304  workers/             inbound, outbound, webhooks, maintenance305  cli.ts               CLI d'exploitation306db/migrations/         001_init · 002_api · 003_templates (28 tables)307web/                   webmail React + TypeScript (151 fichiers TS/TSX, 31 390 lignes) — voir web/README.md308  src/jmap/ mail/ state/ ui/ admin/ templates/ i18n/ styles/309packages/mcp/          serveur MCP stdio (@spboucher/spmail-mcp)310packages/sdk-ts/       SDK TypeScript (@spboucher/spmail), types générés depuis l'OpenAPI311packages/sdk-python/   SDK Python (spmail), types générés312packages/swift-example/ paquet Swift SPMailClient + exécutable d'exemple313infra/mail-edge/       installation épinglée de Stalwart, plans déclaratifs (bootstrap, durcissement)314infra/backup/          sauvegarde chiffrée du courrier, copie hors machine, test de restauration315infra/monitoring/      surveillance du serveur de courrier316tests/                 harnais + intégration (vrai serveur, vraie base, vrai Stalwart), e2e Playwright (3 configurations)317scripts/               build, pile de dev, préparation du nœud, sauvegarde de la base, OpenAPI, CLI de prod318docs/                  14 documents + docs/brand/ (logo, icône)319```320321## 🚀 Développer322323```bash324pnpm install325ssh -f -N -L 18080:127.0.0.1:8080 BHS64          # Stalwart réel (domaine de recette stg.spboucher.ai)326createdb sp_mail_dev327pnpm build && scripts/dev.sh node dist/server.mjs  # http://localhost:8731 (secrets lus hors dépôt)328scripts/dev.sh node dist/cli.mjs bootstrap         # lien du premier administrateur (dev)329pnpm dev:web                                       # Vite sur :5193, proxy /api → 8731330```331332`scripts/dev.sh` fixe `PORT=8731`, `DATABASE_URL=postgres://127.0.0.1/sp_mail_dev`, `SPMAIL_RP_ID=localhost` et lit les secrets dans le dossier désigné par `SPMAIL_SECRETS` (hors dépôt).333334| Script `pnpm` | Effet |335|---|---|336| `dev:server` | `tsx watch server/src/index.ts` |337| `dev:web` | Vite |338| `build` | `scripts/build.mjs` (esbuild → `dist/server.mjs`, `dist/cli.mjs`) puis `vite build` (`dist/web`) |339| `start` · `cli` | `node dist/server.mjs` · `node dist/cli.mjs` |340| `typecheck` | `tsc -p .` |341| `test` · `test:web` · `test:e2e` · `test:sdk` | voir [Tester](#-tester) |342| `openapi` | régénère `docs/OPENAPI.yaml` depuis le registre des routes |343| `audit` | `pnpm audit --prod` |344345### CLI d'exploitation (`node dist/cli.mjs <commande>`)346347`bootstrap` · `recover` · `invite` · `mailbox-add` · `aliases-set` · `status` · `dns` · `revoke-sessions` · `dev-token` · `addresses-sync` · `key-create` · `key-revoke` · `template-import` · `migrate`348349```bash350node dist/cli.mjs bootstrap            # lien à usage unique du premier administrateur351node dist/cli.mjs recover <handle>     # appareil perdu ([--revoke-passkeys])352node dist/cli.mjs mailbox-add info@spboucher.ai <handle> --name "Simon-Pierre Boucher"353node dist/cli.mjs status | dns | revoke-sessions <handle>354node dist/cli.mjs key-create <nom> --scopes mail.send --addresses notifications@spboucher.ai \355    [--external allow|approval|deny] [--rate N] [--daily N] [--expires ISO] [--all-addresses]356node dist/cli.mjs key-revoke <id de clé | spm_préfixe>357```358359En production, `scripts/prod-cli.sh` lance le CLI avec l'environnement du processus PM2 `sp-mail`, sans afficher de secret.360361## ⚙️ Configuration362363Noms seulement ; les valeurs par défaut non secrètes sont dans [`.env.example`](.env.example), les secrets vivent hors dépôt (manifeste `mld`).364365| Variable | Rôle |366|---|---|367| `PORT`, `HOST` | écoute du backend (8730 en production) |368| `DATABASE_URL` | PostgreSQL |369| `SPMAIL_ORIGIN`, `SPMAIL_RP_ID` | origine du site et identifiant de partie de confiance WebAuthn |370| `SPMAIL_TRUST_PROXY` | adresse du mandataire de confiance (Caddy) |371| `SPMAIL_STALWART_URL`, `SPMAIL_STALWART_ADMIN_USER`, `SPMAIL_STALWART_ADMIN_PASSWORD` | API de Stalwart et compte de gestion (**secret**) |372| `SPMAIL_MASTER_KEY` | clé maîtresse qui scelle les secrets de boîtes (**secret**) |373| `SPMAIL_APPLE_APP_IDS` | App ID servis par `/.well-known/apple-app-site-association` |374| `SPMAIL_MX_HOST`, `SPMAIL_MX_IP` | attendus par le contrôle DNS de l'administration |375| `SPMAIL_VERSION` | version annoncée par les routes de santé |376| `SPMAIL_WEB_DIR`, `SPMAIL_BACKUP_STATUS` | dossier du build web, fichier d'état des sauvegardes |377| `SPMAIL_WORKERS` | `off` désactive les travailleurs en processus |378| `SPMAIL_PROTECTED_ADDRESSES` | adresses jamais supprimables ni modifiables de façon destructive |379| `SPMAIL_WATCH_INTERVAL_MS`, `SPMAIL_WORKER_TICK_MS`, `SPMAIL_EXPIRY_INTERVAL_MS` | périodes du veilleur de réception, des files, de l'expiration |380| `SPMAIL_WEBHOOK_BACKOFF` | délais de nouvelle tentative des webhooks (secondes) |381| `SPMAIL_FILE_TTL_MINUTES` | durée de vie d'un fichier téléversé par `POST /api/v1/files` |382| `SPMAIL_AI_MODEL`, `ANTHROPIC_API_KEY` (ou `ANTHROPIC_AUTH_TOKEN`) | modèle et accès de la génération de modèles (**secret**, facultatif : sans clé, `503 ai_not_configured`) |383| `SPMAIL_TREAT_AS_EXTERNAL`, `SPMAIL_VALIDATE_RESPONSES` | **tests seulement**, refusées sur une origine https |384385## 🔌 API386387Trois surfaces, documentées en détail dans `docs/` :388389| Surface | Préfixe | Authentification | Contrat |390|---|---|---|---|391| Session (web, natif) | `/api/…` | cookie `__Host-spmail_session` ou jeton porteur natif | [`docs/api-contract.md`](docs/api-contract.md), [`docs/templates-api.md`](docs/templates-api.md) |392| Passerelle JMAP | `/api/jmap/{boîte}/…` | session | RFC 8620/8621 |393| API universelle | `/api/v1/…` | clé `spm_…`, jeton d'exploration `spx_…` ou session | [`docs/API.md`](docs/API.md), [`docs/OPENAPI.yaml`](docs/OPENAPI.yaml) (aussi `GET /api/v1/openapi.json`) |394395<details>396<summary><b>Routes de session — identité, courrier, images</b></summary>397398| Route | Rôle |399|---|---|400| `POST /api/login/options` · `POST /api/login/verify` | connexion par passkey (aucun nom d'utilisateur) |401| `POST /api/enroll/check` · `/options` · `/verify` | enrôlement par lien `/enroll#<jeton>` (`bootstrap`, `recover`, `invite`) |402| `POST /api/reauth/options` · `/verify` | ré-authentification (5 min) |403| `POST /api/logout` · `GET /api/me` · `PUT /api/profile` · `GET /api/usage` · `PUT`/`PATCH /api/prefs` | session, profil, usage, préférences (≤ 20 ko) |404| `GET /api/passkeys` · `POST /api/passkeys/options` · `/verify` · `DELETE /api/passkeys/:id` | gestion des clés (la dernière ne peut pas être retirée) |405| `GET /api/sessions` · `DELETE /api/sessions/:id` | appareils connectés, révocation |406| `POST /api/push/register` | natif : jeton APNs |407| `GET /api/jmap/{mb}/session` | objet Session JMAP, URL pointant vers la passerelle |408| `POST /api/jmap/{mb}/api` | requête JMAP (≤ 10 Mo, ≤ 16 appels) |409| `POST /api/jmap/{mb}/upload/{accountId}/` | corps binaire brut (≤ 50 Mo) |410| `GET /api/jmap/{mb}/download/{accountId}/{blobId}/{name}` | toujours `attachment` + `CSP: sandbox`, sauf `inline=1` pour png/jpeg/gif/webp |411| `GET /api/jmap/{mb}/eventsource` | SSE `event: state` |412| `GET /api/img?u=…` | mandataire d'images, sur action explicite seulement |413| `GET /api/health/live` · `GET /api/health/ready` | sans authentification |414| `GET /.well-known/apple-app-site-association` | Associated Domains des apps Apple |415416</details>417418<details>419<summary><b>Routes du studio de modèles</b></summary>420421| Route | Rôle |422|---|---|423| `GET`/`POST /api/templates` · `GET`/`PUT`/`DELETE /api/templates/:id` | bibliothèque (la suppression archive) |424| `POST /api/templates/:id/unarchive` · `/duplicate` | annulation d'archivage (< 30 jours), copie |425| `GET /api/templates/:id/versions` · `/versions/:n` · `POST …/restore` | historique (50 dernières), restauration |426| `POST /api/templates/:id/render` · `POST /api/templates/preview` | rendu avec valeurs échappées ; brouillon non enregistré |427| `POST /api/templates/generate` | génération ou retouche par IA, `text/event-stream` (`start`, `progress`, `done`, `error`) |428| `GET /api/templates/ai/usage` | usage des 30 derniers jours |429430Limite : 30 générations par heure et par utilisateur ; durée observée 60 à 150 s. Seuls le brief, la marque et, pour une retouche, le modèle de base sont envoyés à l'API d'Anthropic — jamais de contenu de boîte aux lettres.431432</details>433434<details>435<summary><b>Routes d'administration (<code>role = admin</code>)</b></summary>436437| Route | Rôle |438|---|---|439| `GET /api/admin/overview` · `/dns` · `/users` · `/audit` · `/metrics` | état du serveur, DNS en direct, utilisateurs, audit, métriques |440| `POST /api/admin/mailboxes` · `/mailboxes/adopt` · `DELETE /api/admin/mailboxes/:id[?purge=delete-all-mail]` | créer, adopter, détacher (purge explicite) |441| `PUT /api/admin/mailboxes/:id/aliases` · `GET`/`PUT …/grants` | alias, droits partagés |442| `POST /api/admin/addresses/sync` | resynchroniser les adresses avec le serveur de courrier |443| `GET`/`POST /api/admin/api-keys` · `GET`/`PATCH`/`DELETE …/:id` · `…/usage` · `…/rotate` · `…/explorer-token` | clés d'API |444| `GET /api/admin/approvals` · `POST …/:id/approve` · `…/reject` | envois externes en attente |445| `GET /api/admin/scheduled` · `DELETE …/:id` | messages programmés |446| `GET`/`POST`/`DELETE /api/admin/webhook-allowlist` | destinations internes permises aux webhooks |447| `POST /api/admin/queue/:id/retry` · `POST /api/admin/retention/run` | file d'attente, conservation |448449</details>450451### `/api/v1` — 54 opérations sur 39 chemins452453| Groupe | Routes principales | Portée |454|---|---|---|455| Introspection | `GET /health`, `/openapi.json`, `/openapi.yaml` (publiques), `GET /me` | — |456| Envoi | `POST /messages/send`, `/send-batch`, `/messages/{id}/reply`, `/forward`, `/drafts/{id}/send` | `mail.send` |457| Suivi | `GET /messages/outbound[/{id}]`, `GET /messages/scheduled`, `DELETE /messages/scheduled/{id}` | `mail.send` |458| Lecture | `GET /messages`, `/messages/{id}`, `/threads`, `/threads/{id}`, `/messages/changes`, `/folders` | `mail.read` (+ `mail.search`) |459| Modification | `PATCH /messages/{id}`, `POST /messages/{id}/move`, `DELETE /messages/{id}`, `POST /folders` | `mail.modify` / `mail.delete` |460| Brouillons, fichiers | `/drafts…`, `POST /files`, `GET /messages/{id}/attachments[/{id}]` | `mail.drafts`, `mail.attachments.*` |461| Adresses | `/addresses…`, `/aliases…`, `/addresses/{id}/automation` | `mail.addresses.*`, `mail.aliases.manage` |462| Webhooks | `/webhooks…`, `POST /webhook-deliveries/{id}/replay`, `GET /events` | `mail.webhooks.manage` |463| Modèles | `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/render` ; envoi par `template_id` + `variables` dans `/messages/send` | voir `docs/API.md` § 15b |464465Les 13 portées : `mail.send`, `mail.read`, `mail.search`, `mail.modify`, `mail.delete`, `mail.drafts`, `mail.attachments.read`, `mail.attachments.write`, `mail.addresses.read`, `mail.addresses.manage`, `mail.aliases.manage`, `mail.webhooks.manage`, `mail.admin` (implique toutes les autres).466467Conventions : enveloppe d'erreur unique `{"error":{"code","message","details"}}`, `X-Request-Id` sur chaque réponse, pagination par curseur opaque (1–100, défaut 25), `Idempotency-Key` conservée 24 h (empreinte sur JSON canonique, insensible à l'ordre des clés), plafonds par clé (`rate_per_minute` 60, `daily_send_limit` 200 par défaut) et garde globale de 3 000 requêtes/minute par IP. Un jeton dans une URL est refusé (`400 token_in_url`).468469**États de remise** : `queued`, `scheduled`, `pending_approval`, `sent`, `deferred`, `delivered`, `bounced`, `failed`, `cancelled`. `delivered` = accepté par le serveur du destinataire (2xx), **pas** une preuve d'arrivée en boîte de réception.470471## 🗄 Modèle de données47247328 tables PostgreSQL en trois migrations ; le courrier lui-même est dans Stalwart (RocksDB), jamais dans cette base.474475| Migration | Tables |476|---|---|477| `001_init.sql` | `users`, `passkeys`, `sessions`, `challenges`, `enrollment_tokens`, `mailboxes`, `push_devices`, `audit_log` |478| `002_api.sql` | `addresses`, `mailbox_grants`, `mailbox_automation`, `api_keys`, `explorer_tokens`, `api_usage`, `idempotency_keys`, `outbound_messages`, `send_approvals`, `files`, `webhooks`, `webhook_events`, `webhook_deliveries`, `webhook_internal_allowlist`, `mailbox_sync`, `watched_messages`, `worker_state` |479| `003_templates.sql` | `templates`, `template_versions`, `ai_generations` |480481```mermaid482erDiagram483    users ||--o{ passkeys : possede484    users ||--o{ sessions : ouvre485    users ||--o{ mailboxes : detient486    users ||--o{ templates : ecrit487    mailboxes ||--o{ addresses : porte488    mailboxes ||--o{ mailbox_grants : partage489    users ||--o{ mailbox_grants : recoit490    api_keys ||--o{ api_usage : journalise491    api_keys ||--o{ explorer_tokens : delegue492    webhooks ||--o{ webhook_deliveries : livre493    webhook_events ||--o{ webhook_deliveries : declenche494    templates ||--o{ template_versions : archive495```496497Ce qui n'est jamais stocké en clair : jetons de session et secrets de clés d'API (SHA-256 seulement), secrets de boîtes (scellés AES-256-GCM par la clé maîtresse).498499## 🤝 Intégrations : clés, SDK, MCP, webhooks500501Guide complet : [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md) (recettes VQuant, SP Wallet, grappe MacLustr, agents IA, apps natives).502503**Principes** : de service à service en HTTPS ; une clé par application ; le moins de droits possible (portées = *quoi*, liste d'adresses = *pour qui*, plafonds, politique d'envoi externe) ; l'expéditeur est imposé par le serveur ; l'envoi vers l'extérieur est gardé (`external_send_policy: approval` par défaut → `202 pending_approval`) ; la clé reste côté serveur (`SPMAIL_API_KEY`).504505```bash506curl -s https://mail.spboucher.ai/api/v1/me -H "Authorization: Bearer $SPMAIL_API_KEY"507# → portées, adresses (can_send, read: full | restricted | none), plafonds, politique d'envoi externe, usage du jour508```509510| Paquet | Nom · version | Doc |511|---|---|---|512| SDK TypeScript | `@spboucher/spmail` 1.0.0 | [`packages/sdk-ts/README.md`](packages/sdk-ts/README.md) |513| SDK Python | `spmail` 1.0.0 (Python ≥ 3.10) | [`packages/sdk-python/README.md`](packages/sdk-python/README.md) |514| Paquet Swift | `SPMailClient` (macOS 15, iOS 18, Swift 6) | [`packages/swift-example/README.md`](packages/swift-example/README.md) |515| Serveur MCP | `@spboucher/spmail-mcp` 1.0.0 | [`packages/mcp/README.md`](packages/mcp/README.md) |516517### Serveur MCP (agents IA)518519```bash520cd packages/sdk-ts && pnpm install --ignore-workspace521cd ../mcp && pnpm install --ignore-workspace && pnpm build          # → packages/mcp/dist/index.js522claude mcp add spmail --env SPMAIL_API_KEY=spm_xxxxxxxxxx_… -- node /chemin/absolu/vers/sp-mail/packages/mcp/dist/index.js523# agent de lecture : ajouter  --env SPMAIL_MCP_READONLY=1524```52552617 outils — lecture : `spmail_list_accounts`, `spmail_list_messages`, `spmail_search`, `spmail_get_message`, `spmail_get_thread`, `spmail_list_attachments`, `spmail_download_attachment`, `spmail_delivery_status`, `spmail_list_templates` ; écriture : `spmail_create_draft`, `spmail_send`, `spmail_send_template`, `spmail_reply`, `spmail_forward`, `spmail_archive`, `spmail_mark_read`, `spmail_move`. Les outils dont la clé n'a pas la portée ne sont pas enregistrés.527528Garde-fous : le contenu des courriels est rendu comme **donnée non fiable** (clé `untrusted`, avertissement fixe, HTML converti en texte, caractères invisibles retirés, vraie destination des liens) ; rien n'est exécuté, suivi ou ouvert ; chaque outil d'envoi redit l'expéditeur et les destinataires ; destinataire externe + politique `approval` → « NOT SENT » ; pas de suppression définitive, pas de gestion d'adresses ni de clés, pas de pièce jointe sortante.529530### Webhooks531532Signés, avec reprise (`SPMAIL_WEBHOOK_BACKOFF`), rejeu d'une livraison, refus des destinations privées (SSRF) sauf liste d'autorisation interne tenue par un administrateur. Vérification de signature : exemples dans `docs/API.md` § 11.4 et dans chaque SDK.533534## 🔐 Sécurité et vie privée535536| Menace | Mesure en place |537|---|---|538| Relais ouvert | un destinataire non local n'est accepté que d'une session authentifiée ; aucun AUTH sur le port 25 ; pas de submission publique (`550 5.7.1 Relay not allowed`) |539| Vol de mot de passe / hameçonnage | aucune connexion par mot de passe : passkeys liées à `mail.spboucher.ai` |540| Vol de session | cookie `__Host-`, HttpOnly, Secure, SameSite=Strict ; jeton natif au trousseau ; SHA-256 seulement en base ; inactivité 30 j, durée max 180 j ; révocation par appareil |541| CSRF | non-GET : `Origin` identique + en-tête `X-SPMail` (web) ; le natif n'a pas d'`Origin` et porte un jeton |542| Accès entre comptes | boîte résolue par `(id, utilisateur de la session)` ; la boîte d'autrui répond 404 ; un compte Stalwart par boîte |543| Élévation vers la gestion du serveur | `urn:stalwart:jmap` et méthodes `x:*` refusées ; comptes de boîte au rôle utilisateur |544| XSS par courriel HTML | assainissement + cadre isolé sans scripts ; CSP stricte (`script-src 'self'`) ; pièces jointes en `attachment` + `CSP: sandbox` |545| Pixels de suivi | contenu distant bloqué par défaut ; affichage sur demande par `/api/img` (le serveur distant ne voit ni IP ni cookies du lecteur) |546| SSRF | http/https, ports 80/443, résolution DNS vérifiée, plages privées/loopback/lien-local/CGNAT refusées, redirections revérifiées, images matricielles seulement, 10 Mo |547| Logiciels malveillants | ClamAV à l'étape DATA : 550 ; 4xx si l'antivirus est indisponible |548| Force brute / balayage | bannissement automatique Stalwart (24 h ; 7 j pour le balayage) ; limites de débit du backend |549| Usurpation d'expéditeur par une application | `From`, `Sender`, `Return-Path` construits par le serveur ; une adresse créée par API n'entre dans la liste d'aucune clé |550| Injection par le contenu | aucun en-tête, objet ou corps ne peut changer une portée, une liste d'adresses ou une politique |551| Fuite par les journaux | méthode, chemin sans chaîne de requête, statut, IP ; jamais de corps, cookie ni jeton |552| Fuite de secrets par le dépôt | secrets hors dépôt (manifeste `mld`, fichiers `0600` sur la passerelle) |553554- **Biométrie ≠ clé d'accès** : Touch ID / Face ID déverrouille localement la passkey ; le serveur ne reçoit qu'une signature. Chaque appareil a sa propre session, révocable à distance.555- **Appareil perdu** : `DELETE /api/sessions/:id` depuis un autre appareil ; tout perdu : `cli recover <handle> [--revoke-passkeys]` (accès SSH au nœud requis).556557**Limites déclarées** ([`docs/security-model.md`](docs/security-model.md)) : pas de chiffrement de bout en bout (TLS opportuniste entre serveurs) ; pas de chiffrement au repos du disque de la passerelle (les *sauvegardes* sont chiffrées) ; le compte de gestion Stalwart détenu par le backend est un secret à privilèges élevés ; dépendances non éliminables : GoDaddy (registre + DNS), OVH (IP, PTR, machine), Let's Encrypt, Apple, listes DNSBL.558559## 🧪 Tester560561```bash562pnpm typecheck563createdb sp_mail_test && pnpm test     # intégration : passkeys, cloisonnement, envoi réel avec pièce jointe, révocation, SSRF, API v1564pnpm test:web                          # logique du webmail (assainisseur HTML, Sieve, adresses…)565pnpm test:e2e                          # Playwright (bureau + mobile), authentificateur virtuel566pnpm test:sdk                          # SDK TypeScript, Python, Swift et serveur MCP567npx playwright test -c tests/e2e/studio/playwright.config.ts   # studio de modèles568npx playwright test -c tests/e2e/admin/playwright.config.ts    # administration, boîte unifiée, alias569node --import tsx --test server/src/template-sanitize.test.ts  # assainisseur de modèles570```571572Les tests n'utilisent que des boîtes `…@stg.spboucher.ai` créées puis purgées, et n'écrivent à aucune adresse externe.573574| Suite | Fichiers | Tests (comptés dans le dépôt) |575|---|---|---|576| Intégration backend (`pnpm test`) | `api.test.ts` 11 · `templates.test.ts` 7 · `v1-addresses` 10 · `v1-keys` 11 · `v1-mail` 10 · `v1-templates` 4 · `v1-unit` 8 · `v1-webhooks` 6 | **67** |577| Assainisseur de modèles | `server/src/template-sanitize.test.ts` | **4** |578| Logique du webmail (`pnpm test:web`) | 12 fichiers `web/src/**/*.test.ts` (dont un corpus XSS de 80 cas) | **177** |579| e2e webmail | `desktop.spec.ts` 19 · `mobile.spec.ts` 5 (390×844) | **24** |580| e2e administration | 12 fichiers `tests/e2e/admin/*.spec.ts` | **34** |581| e2e studio | `templates.spec.ts` 24 · `templates-phone.spec.ts` 3 | **27** |582| SDK + MCP (`pnpm test:sdk`) | `sdk-ts` 17 · `sdk-python` 1 (lance 23 tests unittest) · `sdk-swift` 2 (8 tests + exemple) · `mcp-server` 11 | **31** |583584Résultats observés, preuves et statuts : [`docs/test-report.md`](docs/test-report.md). Le lanceur e2e (`tests/e2e/global-setup.ts`) vide la base `sp_mail_webdev`, démarre le backend sur **8751**, émet le lien d'amorçage et utilise un authentificateur WebAuthn virtuel (CDP) ; sorties dans `/tmp/spmail-e2e`. `E2E_KEEP_SERVER=1` laisse le backend en marche ; `E2E_BULK=2000` réduit l'essai de grande liste (10 000 par défaut). `SPMAIL_TEST_AI=1` active les appels réels (payants) à l'IA.585586## 📦 Déployer, sauvegarder, restaurer, mettre à jour587588Voir [`docs/deployment.md`](docs/deployment.md) et [`docs/disaster-recovery.md`](docs/disaster-recovery.md).589590| Élément | Machine | Gestion |591|---|---|---|592| Stalwart 1.1.1 (épinglé), `stalwart-cli` 2.0.0 | BHS64 | `systemctl … stalwart` |593| Certificat `mx1.spboucher.ai` | BHS64 | obtenu par Caddy, recopié par `sp-mail-cert.path` |594| ClamAV + milter | BHS64 | `clamav-daemon`, `clamav-milter` |595| Sauvegarde du courrier | BHS64 | `sp-mail-backup.timer` (03:20) |596| Backend + web | M4M64c, `~/apps/sp-mail` (clone git, origin spbgit) | PM2 `sp-mail` (port 8730), orchestrateur `mld` |597| Base du backend | M4M64c, PostgreSQL 17, base `sp_mail` | PM2 `sp-mail-backup` (03:45) |598| Copie des sauvegardes du courrier | M4M64c | PM2 `sp-mail-edge-pull` (03:50) |599| Route publique | BHS64, Caddy `mail.spboucher.ai` → nœud par WireGuard | `mld tunnel` |600601```bash602# mise à jour du backend/web (sur le nœud — remote-first)603ssh M4M64c 'cd ~/apps/sp-mail && git pull --ff-only && export PATH=/opt/homebrew/bin:$PATH && pnpm install --frozen-lockfile && pnpm build && pm2 restart sp-mail'604# sauvegarde immédiate du courrier + test de restauration605ssh BHS64 'sudo sp-mail-edge-backup && sudo sp-mail-restore-test'606# état607ssh BHS64 'sudo sp-mail-monitor' ; curl https://mail.spboucher.ai/api/health/ready608```609610**Installer le serveur de courrier depuis zéro** : `infra/mail-edge/install-stalwart.sh` (binaire épinglé, utilisateur, unité systemd), puis `stalwart-cli … apply --file plan-bootstrap.ndjson`, création du compte de gestion, `plan-hardening.ndjson` et `Action/ReloadSettings` — séquence complète dans `docs/deployment.md`. Les écouteurs, magasins et `proxyTrustedNetworks` ne changent qu'au redémarrage.611612**Mettre à jour Stalwart** : lire les notes de version ; sauvegarde ; `STALWART_VERSION=vX.Y.Z sudo -E bash install-stalwart.sh` ; redémarrage ; test SMTP + JMAP. Une version plus récente peut écrire des données illisibles par l'ancienne : le retour arrière passe par la restauration.613614| Données | Méthode | Fréquence | Copies |615|---|---|---|---|616| Courrier, index, file, comptes, clés DKIM, configuration | arrêt de Stalwart (~1 s), `tar --zstd`, AES-256 (PBKDF2 200 000) | 03:20 | 5 sur BHS64 + 14 sur M4M64c (tirées par une clé SSH à commande forcée, SHA-256 vérifié) |617| Base du backend | `pg_dump -Fc`, AES-256, restauration de contrôle dans une base jetable | 03:45 | 30 sur M4M64c |618619**RPO** 24 h · **RTO** visé 1 à 2 h sur une machine Linux neuve à IP fixe. `sudo sp-mail-restore-test` déchiffre la dernière archive, démarre une **seconde instance** Stalwart dessus et compare domaines et comptes à la production, sans y toucher ; à refaire après chaque mise à jour de Stalwart et au moins une fois par trimestre. Procédures de restauration, rotation (DKIM, secret de boîte, compte de gestion) et continuité : `docs/disaster-recovery.md`. DNS : `docs/dns-before.md`, `dns-change-plan.md`, `dns-rollback.md`.620621**Surveillance** : `mld heal` (PM2 + route toutes les 5 min), healthcheck `/api/health/ready`, panneau d'administration (état du serveur, DNS en direct, file, certificats, sauvegarde), `infra/monitoring/sp-mail-monitor.sh`.622623## 🧯 Pièges et comportements à connaître624625- **« Créé » ≠ « remis »** : une soumission acceptée veut dire « accepté pour livraison ». L'état réel se lit dans `EmailSubmission/get → deliveryStatus` (JMAP) ou dans le suivi `/api/v1`. Tout client doit le lire.626- **Limite du serveur de courrier** : au-delà d'environ 25 messages/heure pour un couple domaine expéditeur → destinataire, la soumission est « créée » mais la remise échoue (`452 4.4.5 Rate limit exceeded`).627- **Stalwart ne valide pas l'en-tête `From`** contre le compte authentifié : SP Mail est le point de contrôle, d'où le `From` toujours construit par le serveur.628- **Le FAI résidentiel bloque le port 25 sortant** : un test SMTP depuis un poste à domicile échoue par délai, ce n'est pas une panne du serveur.629- **Idempotence** : l'empreinte est calculée sur du JSON canonique ; même clé + requête différente → `409 idempotency_conflict`. `POST /files` n'est pas idempotent.630- **`PATCH /drafts/{id}` renvoie un nouvel identifiant.**631- **Plafond par minute en mémoire** : il repart avec le processus ; plafond quotidien, files, programmations et webhooks sont persistants.632- **Envoi « au moins une fois »** à la frontière avec le serveur de courrier : si le processus meurt entre l'acceptation par Stalwart et l'enregistrement, le message est soumis de nouveau après l'expiration du bail (2 min).633- **Fichiers téléversés** : Stalwart ne garde les blobs non attachés qu'un temps limité (`400 file_expired`) — téléverser peu avant d'envoyer.634- **Rédaction et modèles** : la rédaction n'accepte qu'une mise en forme simple ; un modèle n'y est pas inséré, on l'envoie par « Envoyer ce modèle » (`template_id` + `variables`).635- **Cadre d'un message** : sa hauteur peut être mal mesurée si ses règles `@media` changent à la largeur du volet.636- **Sans la clé maîtresse**, les boîtes restent intactes mais doivent être ré-adoptées (`cli mailbox-add … --adopt`).637- **Aucune console web Stalwart n'est exposée** : elle reste joignable par un tunnel SSH vers la passerelle.638639## 🧭 Limites connues et non fait640641Relevé de `docs/test-report.md`, `docs/API.md` § 14 et `docs/security-model.md` :642643- **Jamais exercé** : connexion par vraie passkey Touch ID / Face ID (tests avec authentificateur logiciel ou virtuel) ; écrans d'administration et studio avec le compte réel du propriétaire ; réception externe sur chaque alias ; délivrabilité vers plusieurs fournisseurs ; essais de charge, de force brute, de coupure réseau, de disque plein.644- **Non implémenté** : notifications push APNs (les apps enregistrent leur jeton, aucun émetteur côté serveur) ; annulation d'envoi dans le webmail ; service worker (le hors-ligne ne vaut que pour un onglet déjà ouvert) ; images d'arrière-plan CSS ; barre de quota ; téléversement `multipart/form-data` ; suivi d'ouverture ou de clic (par choix).645- **API** : réception détectée par interrogation (5 s), pas par flux ; `message.read` / `message.deleted` au mieux ; tri du plus récent au plus ancien seulement ; rebonds reçus plus tard par DSN non corrélés ; transfert entre boîtes refusé ; transfert automatique à une seule destination, sur un domaine hébergé.646- **Ouverts** : journal d'utilisation d'une clé non paginé (200 derniers appels) ; les listes de messages programmés ne portent pas l'objet ; alertes actives (file bloquée, disque, certificat, liste noire) non faites ; pas de troisième site de sauvegarde.647648## 📚 Documentation649650| Document | Contenu |651|---|---|652| [`docs/00-feasibility.md`](docs/00-feasibility.md) | faits relevés, gate G0, décisions |653| [`docs/architecture.md`](docs/architecture.md) | composants, flux, frontières de confiance |654| [`docs/api-contract.md`](docs/api-contract.md) | API de session (passkeys, passerelle JMAP, administration) |655| [`docs/API.md`](docs/API.md) · [`docs/OPENAPI.yaml`](docs/OPENAPI.yaml) | API REST `/api/v1` et contrat OpenAPI 3.1 généré |656| [`docs/templates-api.md`](docs/templates-api.md) | studio de modèles : API de session |657| [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md) | applications, grappe, agents IA, SDK, webhooks, exploitation des clés |658| [`docs/dns-before.md`](docs/dns-before.md) · [`dns-change-plan.md`](docs/dns-change-plan.md) · [`dns-rollback.md`](docs/dns-rollback.md) | DNS : état initial, lots, état d'application, retour arrière |659| [`docs/security-model.md`](docs/security-model.md) | menaces, mesures, limites déclarées |660| [`docs/deployment.md`](docs/deployment.md) | où tourne quoi, secrets, installation, mise à jour, opérations |661| [`docs/disaster-recovery.md`](docs/disaster-recovery.md) | sauvegardes, restauration, RPO/RTO, rotation |662| [`docs/test-report.md`](docs/test-report.md) | tests exécutés, preuves, statuts PASS / FAIL / BLOCKED / NON FAIT |663| [`web/README.md`](web/README.md) | organisation du webmail, tests e2e, studio |664665## 👤 Auteur666667<div align="center">668<img src="docs/brand/icon.png" width="64" height="64" alt=""><br>669670**Simon-Pierre Boucher** — conception, développement, exploitation<br>671[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai672673</div>674675## 📄 Licence676677`UNLICENSED` (`package.json`, dépôt privé) — tous droits réservés © 2026 Simon-Pierre Boucher.678
Files main
Menu

Theme