SP Mail — webmail
SPA React + TypeScript (aucun cadriciel CSS, polices système). Le build est servi par le backend (dist/web).
Organisation
src/jmap/— client JMAP typé (session, lots avec références de résultat, téléversement, téléchargement, EventSource, erreurs).src/mail/— logique pure, testée sans navigateur : assainisseur HTML, adresses, Authentication-Results, Sieve, mbox/zip, réponses/transferts, recherche.src/state/— magasin d'état, session (clés d'accès), courrier (liste fenêtrée, actions annulables, synchro delta), rédaction, cache IndexedDB.src/ui/— coquille, liste, lecture, rédaction ;ui/settings/,ui/admin/(console, une section = un module chargé à la demande),ui/templates/(studio de modèles) etui/Unified.tsx(« Toutes les boîtes ») sont chargés à la demande.src/admin/— logique pure de la console : réauthentification avec nouvel essai, portées et profils de clés, OpenAPI → formulaire, exemples cURL / TS / Python, géométrie des graphiques SVG, webhooks.src/templates/— logique pure du studio de modèles : lecteur de flux SSE, rendu sombre forcé, document d'aperçu isolé, variables, poids.src/i18n/— dictionnaires FR (référence) et EN ; ceux du studio (*.templates.ts) et de la console (*.adm.<zone>.ts) sont chargés avec leur module (addMessages).
Développer
pnpm dev:web # Vite sur :5193, /api relayé vers le backend local (:8731)
pnpm typecheck
pnpm test:web # tests unitaires (node:test + jsdom), dont le corpus XSS de l'assainisseur
pnpm build # serveur + dist/webTests de bout en bout
createdb sp_mail_webdev # une fois
ssh -f -N -L 18080:127.0.0.1:8080 BHS64 # tunnel vers Stalwart (rouvert par le lanceur s'il est tombé)
pnpm build && pnpm test:e2e # projets « desktop » puis « mobile » (Chromium)Le lanceur (tests/e2e/global-setup.ts) vide la base sp_mail_webdev, démarre le backend sur 8751 avec le build courant, émet le lien
d'amorçage et utilise un authentificateur WebAuthn virtuel (CDP). Les boîtes d'essai web-*@stg.spboucher.ai sont supprimées à la fin
(global-teardown.ts), puis le backend est arrêté (par le PID du port). Sorties dans /tmp/spmail-e2e (traces, axe.log, captures).
E2E_KEEP_SERVER=1 laisse le backend en marche ; E2E_BULK=2000 réduit l'essai de grande liste (10 000 par défaut).
Studio de modèles (/templates)
Bibliothèque, création par IA et éditeur de modèles de courriel ; contrat : docs/templates-api.md.
- Aperçus : tout HTML de modèle passe par
templates/srcdoc.ts(DOMPurify sur le document entier + seconde passe + CSP internedefault-src 'none'; img-src data:) et n'est affiché que dans un<iframe sandbox>sansallow-scriptsniallow-same-origin(miniatures :sandbox=""). Les imageshttps://du modèle sont récupérées par la page via/api/img?u=puis injectées endata:. - Rendu clair / sombre : aucun script dans le cadre, donc
templates/darkmode.tsréécrit les@media (prefers-color-scheme: …)(condition retirée pour le rendu demandé,not allpour l'autre) ; l'aperçu ne dépend pas du thème du système. - Génération :
POST /api/templates/generatelu parfetch+ReadableStream(templates/sse.ts), annulable (AbortController) ; l'état vit dansstate/templates.ts(T.generation). Temps écoulé et caractères reçus seulement : aucun pourcentage inventé. - Suppression annulable : la requête
DELETEarchive le modèle tout de suite ; « Annuler » le désarchive (POST /api/templates/:id/unarchive). - « Envoyer ce modèle » : envoi réel par
POST /api/v1/messages/sendavectemplate_id+variables(mise en page conservée), depuis n'importe quelle identité (boîte ou alias), avec suivi par destinataire ; le panneau d'API donne le cURL du modèle ($SPMAIL_API_KEY, jamais de jeton). Les variables (description, exemple, obligatoire) s'éditent dans le studio. - Identité de marque :
prefs.templateBrand(PUT /api/prefs, envoyé avec toutes les autres préférences). - « Utiliser dans un message » : la rédaction n'accepte qu'une mise en forme simple (
COMPOSE_ALLOWED_TAGS: ni<style>, ni<img>, ni attributs de tableau). Le modèle n'y est donc pas inséré : le HTML rendu est copié et un message s'ouvre avec l'objet prérempli. - Garde de navigation :
setNavigationGuard(state/session.ts) retient liens internes et bouton Précédent tant que des modifications ne sont pas enregistrées ou qu'une génération est en cours.
createdb sp_mail_tpldev # une fois
pnpm build && npx playwright test -c tests/e2e/studio/playwright.config.ts
E2E_AI=1 npx playwright test -c tests/e2e/studio/playwright.config.ts -g "IA réelle" # un seul essai réel (payant)Pile jetable distincte de celle du webmail : backend sur 8791, base sp_mail_tpldev, aucune boîte ni courrier. La génération est
rejouée depuis tests/e2e/fixtures/generate-welcome.sse (flux réel enregistré) par un petit serveur local vers lequel
page.route détourne la requête. Sorties dans /tmp/spmail-e2e-studio.
Toutes les boîtes, identités d'envoi, console d'administration
- Boîte unifiée (
/u/<vue>) :state/unified.ts+ui/Unified.tsx, bâtis surGET /api/v1/messages(session, curseur composite opaque ; logique pure dansmail/unified.ts). Vues : réception, non lus, favoris, brouillons, envoyés, programmés (/api/v1/messages/scheduled, annulables). Sous-ensemble de boîtes :prefs.unifiedMailboxes, enregistré parPATCH /api/prefs(fusion). Un message s'ouvre dans le lecteur habituel : sa boîte devient la boîte courante (enterMailbox), les actions du lecteur restent du JMAP. L'identifiant JMAP est lu dans l'identifiant/api/v1(decodeV1Id, format deserver/src/v1/ids.ts). Rafraîchissement : étatsEmaildes boîtes retenues (EventSource existants). Raccourcig a. - Identités d'envoi :
mail/identities.ts+state/senders.ts— boîtes et alias (GET /api/v1/addresses, actifs et autorisés à envoyer), groupés par boîte. Une boîte envoie par JMAP (comme avant) ; un alias envoie parPOST /api/v1/messages/send(le serveur vérifie l'adresse et construitFrom; pièces jointes remises parPOST /api/v1/files; suivi parGET /messages/outbound/{id}). Changer d'identité remplace le bloc.spm-signaturesans toucher au texte tapé. - Console (
/admin/<section>) :ui/admin/Admin.tsx(navigation groupée) ; briques communes dansui/admin/kit.tsx—sensitive()(invite de clé d'accès sur403 reauth_required, puis nouvel essai unique),SecretDialog(secret montré une fois, jamais conservé),SafeHtmlFrame(HTML non fiable dans un cadre isolé),AddressPicker.
createdb sp_mail_admindev # une fois
pnpm build && npx playwright test -c tests/e2e/admin/playwright.config.tsPile jetable : backend sur 8811 (travailleurs actifs, crochet d'essai SPMAIL_TREAT_AS_EXTERNAL), base sp_mail_admindev, vrai
Stalwart ; boîtes et alias web-*@stg.spboucher.ai créés puis purgés (contrôle par /api/admin/overview). Sorties dans
/tmp/spmail-e2e-admin.
Choix à connaître
- HTML des messages : DOMPurify + seconde passe (
mail/sanitize.ts), rendu dans<iframe sandbox>sansallow-scriptsniallow-same-origin, CSP internedefault-src 'none'; img-src data:. Les images autorisées sont récupérées par la page (mandataire/api/img, ou passerelle pourcid:) et injectées endata:. La hauteur du cadre vient d'un gabarit invisible mesuré hors du cadre. - Mot-clé
$pinned(propre à SP Mail) : message épinglé, trié en tête de son dossier.$junk/$notjunkaccompagnent le signalement. - Règles et réponse automatique : un seul script Sieve « spmail » (voir
mail/sieve.ts) — sur Stalwart,VacationResponse/setdésactiverait le script de règles. - Téléversement : toujours
application/octet-stream(le vrai type voyage dansEmail/set).