SPB Git

Repository Public

README.md 51.6 KB

SP Mail logo



SP Mail icon

# SP Mail

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.

Author: Simon-Pierre Boucher

mail.spboucher.ai version plateforme langues licence author

Stalwart Fastify React TypeScript Vite PostgreSQL postgres.js Node.js WebAuthn Zod DOMPurify parse5 Anthropic SDK OpenAPI MCP esbuild Playwright axe-core pnpm ClamAV

commits last commit activity language languages size branches tags clones

routes API v1 routes session et admin tables migrations portées outils MCP SDK tests d'intégration tests webmail scénarios e2e tests SDK et MCP accessibilité fichiers TypeScript lignes TypeScript

nœud port PM2 serveur de courrier déploiement tunnel


# Sommaire


# 🚀 SP Mail Next (branche next)

É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é.

Document Contenu
docs/next/AUDIT-NEXT.md état réel du code avant le chantier, défauts trouvés
docs/next/ARCHITECTURE-NEXT.md décisions et contrat /api/next
docs/next/DESIGN-SYSTEM-NEXT.md système de design (clair, sombre, minuit)
docs/next/IMPLEMENTATION-PLAN.md phases et priorités
docs/next/FEATURE-PARITY.md parité web · macOS · iOS · iPadOS, avec ce qui est testé ou seulement compilé
docs/next/TEST-REPORT-NEXT.md essais exécutés et preuves, non testé déclaré
docs/next/RELEASE-NEXT.md mise en production et retour arrière
PUSH · SEARCH · INTELLIGENCE · OPERATIONS-NEXT · PERFORMANCE références par domaine

Ajouts 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.

# 🎯 Vue d'ensemble

SP Mail est la messagerie du domaine spboucher.ai, entièrement auto-hébergée :

  • 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) ;
  • aucun mot de passe : l'identité repose sur des clés d'accès WebAuthn (passkeys), avec une session révocable par appareil ;
  • 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 ;
  • 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 ;
  • 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.

# Famille SP Mail

Élément Dépôt spbgit Rôle
Backend + webmail + API + MCP + SDK sp-mail (ce dépôt) https://mail.spboucher.ai
Apps natives macOS et iOS/iPadOS sp-mail-apple (copie de travail : ~/Desktop/Cluster/apple/SPMail) SwiftUI, socle SPMailCore, hors ligne, mêmes routes

Versions : 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.

# ✨ Fonctionnalités

Domaine Ce que fait le code
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
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
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
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
Boîte unifiée « Toutes les boîtes » : liste paginée sur plusieurs boîtes, pastilles par boîte, arrivée en direct
Identités d'expédition envoi depuis une boîte ou un alias, From construit par le serveur, signature qui suit l'identité
Réglages identités et signatures, filtres Sieve, réponse automatique, sécurité (passkeys, appareils), export .eml / mbox / ZIP
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
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
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)
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
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
Agents IA serveur MCP stdio (17 outils), contenu des courriels rendu comme donnée non fiable, mode lecture seule
Exploitation CLI d'exploitation (14 commandes), sauvegardes chiffrées du courrier et de la base, test de restauration sur une seconde instance, surveillance

# 🏗 Architecture

flowchart LR
  subgraph Internet
    MTA[Serveurs de courrier tiers]
    U[Navigateur · app macOS · app iOS]
    APP[Applications · agents IA<br/>clé spm_… · SDK · MCP]
  end
  subgraph BHS64["Passerelle BHS64 — OVH Beauharnois"]
    direction TB
    S25["Stalwart 1.1.1<br/>SMTP :25 public · mx1.spboucher.ai"]
    SJ["Stalwart JMAP + gestion<br/>:8080 privé (loopback + WireGuard)"]
    DB[("RocksDB<br/>boîtes, index, file d'attente")]
    AV["ClamAV milter"]
    C["Caddy :443<br/>mail.spboucher.ai"]
    BK["Sauvegarde chiffrée 03:20"]
  end
  subgraph MacLustr["MacLustr — nœud M4M64c"]
    API["Backend SP Mail :8730<br/>passkeys · sessions · passerelle JMAP<br/>API v1 · admin · travailleurs"]
    PG[("PostgreSQL 17 · sp_mail<br/>identités, clés, files, secrets scellés")]
    BK2["Copie des sauvegardes 03:50"]
  end
  AI["API Anthropic<br/>génération de modèles"]
  MTA <-- "SMTP + STARTTLS" --> S25
  S25 --- DB
  SJ --- DB
  S25 -- scan --> AV
  U -- HTTPS --> C
  APP -- HTTPS --> C
  C -- WireGuard --> API
  API -- "JMAP (WireGuard, secret par boîte)" --> SJ
  API --- PG
  API -. "brief + marque seulement" .-> AI
  BK -- "clé SSH à commande forcée" --> BK2
Zone Contenu Exposition
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
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
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
Clients web (React/TS), macOS et iOS (SwiftUI, socle SPMailCore) parlent JMAP standard au backend, jamais à Stalwart

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.

# Connexion par clé d'accès puis lecture

sequenceDiagram
    autonumber
    participant C as Client (web / natif)
    participant B as Backend SP Mail
    participant P as PostgreSQL
    participant S as Stalwart (JMAP)
    C->>B: POST /api/login/options
    B->>P: enregistre le défi
    B-->>C: challenge_id + options WebAuthn
    C->>C: Touch ID / Face ID signe le défi
    C->>B: POST /api/login/verify {challenge_id, response, client}
    B->>P: vérifie la signature, crée la session (SHA-256 du jeton)
    B-->>C: cookie __Host-spmail_session (web) ou jeton porteur (natif)
    C->>B: GET /api/me
    B-->>C: utilisateur, session, boîtes
    C->>B: POST /api/jmap/{boîte}/api {using, methodCalls}
    B->>P: résout (boîte, utilisateur de la session), descelle le secret
    B->>S: requête JMAP relayée par WireGuard
    S-->>B: réponses
    B-->>C: réponses (URL réécrites vers la passerelle)

# Envoi par l'API avec garde des destinataires externes

sequenceDiagram
    autonumber
    participant A as Application (clé spm_…)
    participant B as /api/v1
    participant W as Travailleur d'envoi
    participant S as Stalwart
    participant H as Webhook de l'application
    A->>B: POST /messages/send + Idempotency-Key
    B->>B: portée mail.send, adresse autorisée, plafonds
    alt destinataire externe et politique approval
        B-->>A: 202 pending_approval (rien n'est parti)
        Note over B: un administrateur approuve ou rejette (ré-authentification passkey)
    else interne ou politique allow
        B-->>A: msg_out_… (queued / sent)
    end
    W->>S: Email/set + EmailSubmission/set
    S-->>W: deliveryStatus par destinataire
    W->>H: message.sent / delivered / bounced (signé)

# Flux du courrier

  • 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.
  • Envoi : client → EmailSubmission/set (passerelle) → file Stalwart → signature DKIM → livraison directe au MX du destinataire, IPv4 seulement (pas de PTR IPv6). Aucun relais tiers.
  • Lecture : client → https://mail.spboucher.ai/api/jmap/{boîte}/… → backend → Stalwart.
  • Temps réel : EventSource JMAP relayé (états seulement, jamais de contenu). Push iOS (APNs) : prévu, non émis.
Choix écartés (docs/architecture.md)
Écarté Raison
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
IMAP / submission publics inutiles aux trois clients SP Mail ; surface d'attaque et mots de passe d'application en plus. Ouvrables plus tard
ACME intégré de Stalwart Caddy possède déjà 80/443 sur BHS64
IPv6 pour SMTP pas de PTR IPv6 ; Gmail rejette sans PTR
IA dans le chemin de livraison l'IA est un service séparé, optionnel, jamais requis

# 🧱 Pile technique

Couche Technologie Version (lue dans le dépôt) Rôle
Serveur de courrier Stalwart + stalwart-cli 1.1.1 (épinglé) · 2.0.0 SMTP, JMAP, DKIM, antispam, stockage RocksDB
Antivirus ClamAV + milter paquet système analyse à l'étape DATA
Backend Fastify · @fastify/cookie · @fastify/static ^5.12.8 · ^11.1.5 · ^10.1.11 HTTP, sessions, service du build web
Identité @simplewebauthn/server · /browser ^14.1.0 · ^14.0.0 WebAuthn
Base PostgreSQL · postgres 17 · ^4.1.1 identités, clés, files, modèles
Validation Zod ^4.6.7 schémas des routes → OpenAPI 3.1
Assainissement DOMPurify · parse5 ^3.2.6 · ^8.1.1 HTML des messages (web) et des modèles (serveur)
IA @anthropic-ai/sdk ^1.10.0 génération de modèles (optionnelle)
Webmail React · react-dom ^19.3.1 SPA, aucun cadriciel CSS, polices système
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
Tests node:test · jsdom · Playwright · axe — · ^31.0.1 · ^1.65.1 · ^4.14.0 intégration, logique, e2e, accessibilité
MCP @modelcontextprotocol/sdk ^1.20.0 serveur d'outils pour agents
SDK TypeScript @spboucher/spmail 1.0.0 · Python spmail 1.0.0 (≥ 3.10) · Swift SPMailClient (tools 6.0) — clients de /api/v1
Exécution Node.js ≥ 22 engines

# 🗂 Arborescence

text
server/src/            backend Fastify (40 fichiers, 5 629 lignes)
  index.ts             démarrage et assemblage des routes
  auth.ts session.ts   passkeys, enrôlement, sessions par appareil ; reauth.ts : ré-authentification
  jmap.ts mailjmap.ts  passerelle JMAP ; stalwart.ts : gestion du serveur de courrier
  admin.ts adminapi.ts administration (boîtes, DNS, file, clés, approbations, métriques)
  keys.ts              clés d'API, portées, plafonds ; addresses.ts sieve.ts : adresses, automatisation
  images.ts            mandataire d'images anti-SSRF ; sanitize.ts template-sanitize.ts
  templates.ts templates-ai.ts   studio de modèles et génération
  outbound.ts webhooks.ts        suivi d'envoi, webhooks
  v1/                  API REST : registry.ts (une définition = validation + OpenAPI), send, messages,
                       addresses, templates, webhooks, meta
  workers/             inbound, outbound, webhooks, maintenance
  cli.ts               CLI d'exploitation
db/migrations/         001_init · 002_api · 003_templates (28 tables)
web/                   webmail React + TypeScript (151 fichiers TS/TSX, 31 390 lignes) — voir web/README.md
  src/jmap/ mail/ state/ ui/ admin/ templates/ i18n/ styles/
packages/mcp/          serveur MCP stdio (@spboucher/spmail-mcp)
packages/sdk-ts/       SDK TypeScript (@spboucher/spmail), types générés depuis l'OpenAPI
packages/sdk-python/   SDK Python (spmail), types générés
packages/swift-example/ paquet Swift SPMailClient + exécutable d'exemple
infra/mail-edge/       installation épinglée de Stalwart, plans déclaratifs (bootstrap, durcissement)
infra/backup/          sauvegarde chiffrée du courrier, copie hors machine, test de restauration
infra/monitoring/      surveillance du serveur de courrier
tests/                 harnais + intégration (vrai serveur, vraie base, vrai Stalwart), e2e Playwright (3 configurations)
scripts/               build, pile de dev, préparation du nœud, sauvegarde de la base, OpenAPI, CLI de prod
docs/                  14 documents + docs/brand/ (logo, icône)

# 🚀 Développer

bash
pnpm install
ssh -f -N -L 18080:127.0.0.1:8080 BHS64          # Stalwart réel (domaine de recette stg.spboucher.ai)
createdb sp_mail_dev
pnpm build && scripts/dev.sh node dist/server.mjs  # http://localhost:8731 (secrets lus hors dépôt)
scripts/dev.sh node dist/cli.mjs bootstrap         # lien du premier administrateur (dev)
pnpm dev:web                                       # Vite sur :5193, proxy /api → 8731

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).

Script pnpm Effet
dev:server tsx watch server/src/index.ts
dev:web Vite
build scripts/build.mjs (esbuild → dist/server.mjs, dist/cli.mjs) puis vite build (dist/web)
start · cli node dist/server.mjs · node dist/cli.mjs
typecheck tsc -p .
test · test:web · test:e2e · test:sdk voir Tester
openapi régénère docs/OPENAPI.yaml depuis le registre des routes
audit pnpm audit --prod

# CLI d'exploitation (node dist/cli.mjs <commande>)

bootstrap · recover · invite · mailbox-add · aliases-set · status · dns · revoke-sessions · dev-token · addresses-sync · key-create · key-revoke · template-import · migrate

bash
node dist/cli.mjs bootstrap            # lien à usage unique du premier administrateur
node dist/cli.mjs recover <handle>     # appareil perdu ([--revoke-passkeys])
node dist/cli.mjs mailbox-add info@spboucher.ai <handle> --name "Simon-Pierre Boucher"
node dist/cli.mjs status | dns | revoke-sessions <handle>
node dist/cli.mjs key-create <nom> --scopes mail.send --addresses notifications@spboucher.ai \
    [--external allow|approval|deny] [--rate N] [--daily N] [--expires ISO] [--all-addresses]
node dist/cli.mjs key-revoke <id de clé | spm_préfixe>

En production, scripts/prod-cli.sh lance le CLI avec l'environnement du processus PM2 sp-mail, sans afficher de secret.

# ⚙️ Configuration

Noms seulement ; les valeurs par défaut non secrètes sont dans .env.example, les secrets vivent hors dépôt (manifeste mld).

Variable Rôle
PORT, HOST écoute du backend (8730 en production)
DATABASE_URL PostgreSQL
SPMAIL_ORIGIN, SPMAIL_RP_ID origine du site et identifiant de partie de confiance WebAuthn
SPMAIL_TRUST_PROXY adresse du mandataire de confiance (Caddy)
SPMAIL_STALWART_URL, SPMAIL_STALWART_ADMIN_USER, SPMAIL_STALWART_ADMIN_PASSWORD API de Stalwart et compte de gestion (secret)
SPMAIL_MASTER_KEY clé maîtresse qui scelle les secrets de boîtes (secret)
SPMAIL_APPLE_APP_IDS App ID servis par /.well-known/apple-app-site-association
SPMAIL_MX_HOST, SPMAIL_MX_IP attendus par le contrôle DNS de l'administration
SPMAIL_VERSION version annoncée par les routes de santé
SPMAIL_WEB_DIR, SPMAIL_BACKUP_STATUS dossier du build web, fichier d'état des sauvegardes
SPMAIL_WORKERS off désactive les travailleurs en processus
SPMAIL_PROTECTED_ADDRESSES adresses jamais supprimables ni modifiables de façon destructive
SPMAIL_WATCH_INTERVAL_MS, SPMAIL_WORKER_TICK_MS, SPMAIL_EXPIRY_INTERVAL_MS périodes du veilleur de réception, des files, de l'expiration
SPMAIL_WEBHOOK_BACKOFF délais de nouvelle tentative des webhooks (secondes)
SPMAIL_FILE_TTL_MINUTES durée de vie d'un fichier téléversé par POST /api/v1/files
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)
SPMAIL_TREAT_AS_EXTERNAL, SPMAIL_VALIDATE_RESPONSES tests seulement, refusées sur une origine https

# 🔌 API

Trois surfaces, documentées en détail dans docs/ :

Surface Préfixe Authentification Contrat
Session (web, natif) /api/… cookie __Host-spmail_session ou jeton porteur natif docs/api-contract.md, docs/templates-api.md
Passerelle JMAP /api/jmap/{boîte}/… session RFC 8620/8621
API universelle /api/v1/… clé spm_…, jeton d'exploration spx_… ou session docs/API.md, docs/OPENAPI.yaml (aussi GET /api/v1/openapi.json)
Routes de session — identité, courrier, images
Route Rôle
POST /api/login/options · POST /api/login/verify connexion par passkey (aucun nom d'utilisateur)
POST /api/enroll/check · /options · /verify enrôlement par lien /enroll#<jeton> (bootstrap, recover, invite)
POST /api/reauth/options · /verify ré-authentification (5 min)
POST /api/logout · GET /api/me · PUT /api/profile · GET /api/usage · PUT/PATCH /api/prefs session, profil, usage, préférences (≤ 20 ko)
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)
GET /api/sessions · DELETE /api/sessions/:id appareils connectés, révocation
POST /api/push/register natif : jeton APNs
GET /api/jmap/{mb}/session objet Session JMAP, URL pointant vers la passerelle
POST /api/jmap/{mb}/api requête JMAP (≤ 10 Mo, ≤ 16 appels)
POST /api/jmap/{mb}/upload/{accountId}/ corps binaire brut (≤ 50 Mo)
GET /api/jmap/{mb}/download/{accountId}/{blobId}/{name} toujours attachment + CSP: sandbox, sauf inline=1 pour png/jpeg/gif/webp
GET /api/jmap/{mb}/eventsource SSE event: state
GET /api/img?u=… mandataire d'images, sur action explicite seulement
GET /api/health/live · GET /api/health/ready sans authentification
GET /.well-known/apple-app-site-association Associated Domains des apps Apple
Routes du studio de modèles
Route Rôle
GET/POST /api/templates · GET/PUT/DELETE /api/templates/:id bibliothèque (la suppression archive)
POST /api/templates/:id/unarchive · /duplicate annulation d'archivage (< 30 jours), copie
GET /api/templates/:id/versions · /versions/:n · POST …/restore historique (50 dernières), restauration
POST /api/templates/:id/render · POST /api/templates/preview rendu avec valeurs échappées ; brouillon non enregistré
POST /api/templates/generate génération ou retouche par IA, text/event-stream (start, progress, done, error)
GET /api/templates/ai/usage usage des 30 derniers jours

Limite : 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.

Routes d'administration (role = admin)
Route Rôle
GET /api/admin/overview · /dns · /users · /audit · /metrics état du serveur, DNS en direct, utilisateurs, audit, métriques
POST /api/admin/mailboxes · /mailboxes/adopt · DELETE /api/admin/mailboxes/:id[?purge=delete-all-mail] créer, adopter, détacher (purge explicite)
PUT /api/admin/mailboxes/:id/aliases · GET/PUT …/grants alias, droits partagés
POST /api/admin/addresses/sync resynchroniser les adresses avec le serveur de courrier
GET/POST /api/admin/api-keys · GET/PATCH/DELETE …/:id · …/usage · …/rotate · …/explorer-token clés d'API
GET /api/admin/approvals · POST …/:id/approve · …/reject envois externes en attente
GET /api/admin/scheduled · DELETE …/:id messages programmés
GET/POST/DELETE /api/admin/webhook-allowlist destinations internes permises aux webhooks
POST /api/admin/queue/:id/retry · POST /api/admin/retention/run file d'attente, conservation

# /api/v1 — 54 opérations sur 39 chemins

Groupe Routes principales Portée
Introspection GET /health, /openapi.json, /openapi.yaml (publiques), GET /me —
Envoi POST /messages/send, /send-batch, /messages/{id}/reply, /forward, /drafts/{id}/send mail.send
Suivi GET /messages/outbound[/{id}], GET /messages/scheduled, DELETE /messages/scheduled/{id} mail.send
Lecture GET /messages, /messages/{id}, /threads, /threads/{id}, /messages/changes, /folders mail.read (+ mail.search)
Modification PATCH /messages/{id}, POST /messages/{id}/move, DELETE /messages/{id}, POST /folders mail.modify / mail.delete
Brouillons, fichiers /drafts…, POST /files, GET /messages/{id}/attachments[/{id}] mail.drafts, mail.attachments.*
Adresses /addresses…, /aliases…, /addresses/{id}/automation mail.addresses.*, mail.aliases.manage
Webhooks /webhooks…, POST /webhook-deliveries/{id}/replay, GET /events mail.webhooks.manage
Modèles GET /templates, GET /templates/{id}, POST /templates/{id}/render ; envoi par template_id + variables dans /messages/send voir docs/API.md § 15b

Les 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).

Conventions : 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).

É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.

# 🗄 Modèle de données

28 tables PostgreSQL en trois migrations ; le courrier lui-même est dans Stalwart (RocksDB), jamais dans cette base.

Migration Tables
001_init.sql users, passkeys, sessions, challenges, enrollment_tokens, mailboxes, push_devices, audit_log
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
003_templates.sql templates, template_versions, ai_generations
erDiagram
    users ||--o{ passkeys : possede
    users ||--o{ sessions : ouvre
    users ||--o{ mailboxes : detient
    users ||--o{ templates : ecrit
    mailboxes ||--o{ addresses : porte
    mailboxes ||--o{ mailbox_grants : partage
    users ||--o{ mailbox_grants : recoit
    api_keys ||--o{ api_usage : journalise
    api_keys ||--o{ explorer_tokens : delegue
    webhooks ||--o{ webhook_deliveries : livre
    webhook_events ||--o{ webhook_deliveries : declenche
    templates ||--o{ template_versions : archive

Ce 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).

# 🤝 Intégrations : clés, SDK, MCP, webhooks

Guide complet : docs/INTEGRATIONS.md (recettes VQuant, SP Wallet, grappe MacLustr, agents IA, apps natives).

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).

bash
curl -s https://mail.spboucher.ai/api/v1/me -H "Authorization: Bearer $SPMAIL_API_KEY"
# → portées, adresses (can_send, read: full | restricted | none), plafonds, politique d'envoi externe, usage du jour
Paquet Nom · version Doc
SDK TypeScript @spboucher/spmail 1.0.0 packages/sdk-ts/README.md
SDK Python spmail 1.0.0 (Python ≥ 3.10) packages/sdk-python/README.md
Paquet Swift SPMailClient (macOS 15, iOS 18, Swift 6) packages/swift-example/README.md
Serveur MCP @spboucher/spmail-mcp 1.0.0 packages/mcp/README.md

# Serveur MCP (agents IA)

bash
cd packages/sdk-ts && pnpm install --ignore-workspace
cd ../mcp && pnpm install --ignore-workspace && pnpm build          # → packages/mcp/dist/index.js
claude mcp add spmail --env SPMAIL_API_KEY=spm_xxxxxxxxxx_… -- node /chemin/absolu/vers/sp-mail/packages/mcp/dist/index.js
# agent de lecture : ajouter  --env SPMAIL_MCP_READONLY=1

17 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.

Garde-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.

# Webhooks

Signé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.

# 🔐 Sécurité et vie privée

Menace Mesure en place
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)
Vol de mot de passe / hameçonnage aucune connexion par mot de passe : passkeys liées à mail.spboucher.ai
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
CSRF non-GET : Origin identique + en-tête X-SPMail (web) ; le natif n'a pas d'Origin et porte un jeton
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
Élévation vers la gestion du serveur urn:stalwart:jmap et méthodes x:* refusées ; comptes de boîte au rôle utilisateur
XSS par courriel HTML assainissement + cadre isolé sans scripts ; CSP stricte (script-src 'self') ; pièces jointes en attachment + CSP: sandbox
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)
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
Logiciels malveillants ClamAV à l'étape DATA : 550 ; 4xx si l'antivirus est indisponible
Force brute / balayage bannissement automatique Stalwart (24 h ; 7 j pour le balayage) ; limites de débit du backend
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é
Injection par le contenu aucun en-tête, objet ou corps ne peut changer une portée, une liste d'adresses ou une politique
Fuite par les journaux méthode, chemin sans chaîne de requête, statut, IP ; jamais de corps, cookie ni jeton
Fuite de secrets par le dépôt secrets hors dépôt (manifeste mld, fichiers 0600 sur la passerelle)
  • 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.
  • Appareil perdu : DELETE /api/sessions/:id depuis un autre appareil ; tout perdu : cli recover <handle> [--revoke-passkeys] (accès SSH au nœud requis).

Limites déclarées (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.

# 🧪 Tester

bash
pnpm typecheck
createdb sp_mail_test && pnpm test     # intégration : passkeys, cloisonnement, envoi réel avec pièce jointe, révocation, SSRF, API v1
pnpm test:web                          # logique du webmail (assainisseur HTML, Sieve, adresses…)
pnpm test:e2e                          # Playwright (bureau + mobile), authentificateur virtuel
pnpm test:sdk                          # SDK TypeScript, Python, Swift et serveur MCP
npx playwright test -c tests/e2e/studio/playwright.config.ts   # studio de modèles
npx playwright test -c tests/e2e/admin/playwright.config.ts    # administration, boîte unifiée, alias
node --import tsx --test server/src/template-sanitize.test.ts  # assainisseur de modèles

Les tests n'utilisent que des boîtes …@stg.spboucher.ai créées puis purgées, et n'écrivent à aucune adresse externe.

Suite Fichiers Tests (comptés dans le dépôt)
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
Assainisseur de modèles server/src/template-sanitize.test.ts 4
Logique du webmail (pnpm test:web) 12 fichiers web/src/**/*.test.ts (dont un corpus XSS de 80 cas) 177
e2e webmail desktop.spec.ts 19 · mobile.spec.ts 5 (390×844) 24
e2e administration 12 fichiers tests/e2e/admin/*.spec.ts 34
e2e studio templates.spec.ts 24 · templates-phone.spec.ts 3 27
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

Résultats observés, preuves et statuts : 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.

# 📦 Déployer, sauvegarder, restaurer, mettre à jour

Voir docs/deployment.md et docs/disaster-recovery.md.

Élément Machine Gestion
Stalwart 1.1.1 (épinglé), stalwart-cli 2.0.0 BHS64 systemctl … stalwart
Certificat mx1.spboucher.ai BHS64 obtenu par Caddy, recopié par sp-mail-cert.path
ClamAV + milter BHS64 clamav-daemon, clamav-milter
Sauvegarde du courrier BHS64 sp-mail-backup.timer (03:20)
Backend + web M4M64c, ~/apps/sp-mail (clone git, origin spbgit) PM2 sp-mail (port 8730), orchestrateur mld
Base du backend M4M64c, PostgreSQL 17, base sp_mail PM2 sp-mail-backup (03:45)
Copie des sauvegardes du courrier M4M64c PM2 sp-mail-edge-pull (03:50)
Route publique BHS64, Caddy mail.spboucher.ai → nœud par WireGuard mld tunnel
bash
# mise à jour du backend/web (sur le nœud — remote-first)
ssh 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'
# sauvegarde immédiate du courrier + test de restauration
ssh BHS64 'sudo sp-mail-edge-backup && sudo sp-mail-restore-test'
# état
ssh BHS64 'sudo sp-mail-monitor' ; curl https://mail.spboucher.ai/api/health/ready

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.

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.

Données Méthode Fréquence Copies
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é)
Base du backend pg_dump -Fc, AES-256, restauration de contrôle dans une base jetable 03:45 30 sur M4M64c

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.

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.

# 🧯 Pièges et comportements à connaître

  • « 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.
  • 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).
  • 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.
  • 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.
  • 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.
  • PATCH /drafts/{id} renvoie un nouvel identifiant.
  • Plafond par minute en mémoire : il repart avec le processus ; plafond quotidien, files, programmations et webhooks sont persistants.
  • 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).
  • 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.
  • 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).
  • Cadre d'un message : sa hauteur peut être mal mesurée si ses règles @media changent à la largeur du volet.
  • Sans la clé maîtresse, les boîtes restent intactes mais doivent être ré-adoptées (cli mailbox-add … --adopt).
  • Aucune console web Stalwart n'est exposée : elle reste joignable par un tunnel SSH vers la passerelle.

# 🧭 Limites connues et non fait

Relevé de docs/test-report.md, docs/API.md § 14 et docs/security-model.md :

  • 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.
  • 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).
  • 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é.
  • 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.

# 📚 Documentation

Document Contenu
docs/00-feasibility.md faits relevés, gate G0, décisions
docs/architecture.md composants, flux, frontières de confiance
docs/api-contract.md API de session (passkeys, passerelle JMAP, administration)
docs/API.md · docs/OPENAPI.yaml API REST /api/v1 et contrat OpenAPI 3.1 généré
docs/templates-api.md studio de modèles : API de session
docs/INTEGRATIONS.md applications, grappe, agents IA, SDK, webhooks, exploitation des clés
docs/dns-before.md · dns-change-plan.md · dns-rollback.md DNS : état initial, lots, état d'application, retour arrière
docs/security-model.md menaces, mesures, limites déclarées
docs/deployment.md où tourne quoi, secrets, installation, mise à jour, opérations
docs/disaster-recovery.md sauvegardes, restauration, RPO/RTO, rotation
docs/test-report.md tests exécutés, preuves, statuts PASS / FAIL / BLOCKED / NON FAIT
web/README.md organisation du webmail, tests e2e, studio

# 👤 Auteur


Simon-Pierre Boucher — conception, développement, exploitation
www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai

# 📄 Licence

UNLICENSED (package.json, dépôt privé) — tous droits réservés © 2026 Simon-Pierre Boucher.

Files main
Menu

Theme