Repository Public
1# SP Mail — webmail23SPA React + TypeScript (aucun cadriciel CSS, polices système). Le build est servi par le backend (`dist/web`).45## Organisation67- `src/jmap/` — client JMAP typé (session, lots avec références de résultat, téléversement, téléchargement, EventSource, erreurs).8- `src/mail/` — logique pure, testée sans navigateur : assainisseur HTML, adresses, Authentication-Results, Sieve, mbox/zip, réponses/transferts, recherche.9- `src/state/` — magasin d'état, session (clés d'accès), courrier (liste fenêtrée, actions annulables, synchro delta), rédaction, cache IndexedDB.10- `src/ui/` — coquille, liste, lecture, rédaction ; `ui/settings/`, `ui/admin/` (console, une section = un module chargé à la demande),11 `ui/templates/` (studio de modèles) et `ui/Unified.tsx` (« Toutes les boîtes ») sont chargés à la demande.12- `src/admin/` — logique pure de la console : réauthentification avec nouvel essai, portées et profils de clés, OpenAPI → formulaire,13 exemples cURL / TS / Python, géométrie des graphiques SVG, webhooks.14- `src/templates/` — logique pure du studio de modèles : lecteur de flux SSE, rendu sombre forcé, document d'aperçu isolé, variables, poids.15- `src/i18n/` — dictionnaires FR (référence) et EN ; ceux du studio (`*.templates.ts`) et de la console (`*.adm.<zone>.ts`) sont16 chargés avec leur module (`addMessages`).1718## Développer1920```sh21pnpm dev:web # Vite sur :5193, /api relayé vers le backend local (:8731)22pnpm typecheck23pnpm test:web # tests unitaires (node:test + jsdom), dont le corpus XSS de l'assainisseur24pnpm build # serveur + dist/web25```2627## Tests de bout en bout2829```sh30createdb sp_mail_webdev # une fois31ssh -f -N -L 18080:127.0.0.1:8080 BHS64 # tunnel vers Stalwart (rouvert par le lanceur s'il est tombé)32pnpm build && pnpm test:e2e # projets « desktop » puis « mobile » (Chromium)33```3435Le lanceur (`tests/e2e/global-setup.ts`) vide la base `sp_mail_webdev`, démarre le backend sur **8751** avec le build courant, émet le lien36d'amorçage et utilise un authentificateur WebAuthn virtuel (CDP). Les boîtes d'essai `web-*@stg.spboucher.ai` sont supprimées à la fin37(`global-teardown.ts`), puis le backend est arrêté (par le PID du port). Sorties dans `/tmp/spmail-e2e` (traces, `axe.log`, captures).38`E2E_KEEP_SERVER=1` laisse le backend en marche ; `E2E_BULK=2000` réduit l'essai de grande liste (10 000 par défaut).3940## Studio de modèles (`/templates`)4142Bibliothèque, création par IA et éditeur de modèles de courriel ; contrat : `docs/templates-api.md`.4344- **Aperçus** : tout HTML de modèle passe par `templates/srcdoc.ts` (DOMPurify sur le document entier + seconde passe + CSP interne45 `default-src 'none'; img-src data:`) et n'est affiché que dans un `<iframe sandbox>` sans `allow-scripts` ni `allow-same-origin`46 (miniatures : `sandbox=""`). Les images `https://` du modèle sont récupérées par la page via `/api/img?u=` puis injectées en `data:`.47- **Rendu clair / sombre** : aucun script dans le cadre, donc `templates/darkmode.ts` réécrit les `@media (prefers-color-scheme: …)`48 (condition retirée pour le rendu demandé, `not all` pour l'autre) ; l'aperçu ne dépend pas du thème du système.49- **Génération** : `POST /api/templates/generate` lu par `fetch` + `ReadableStream` (`templates/sse.ts`), annulable (`AbortController`) ;50 l'état vit dans `state/templates.ts` (`T.generation`). Temps écoulé et caractères reçus seulement : aucun pourcentage inventé.51- **Suppression annulable** : la requête `DELETE` archive le modèle tout de suite ; « Annuler » le désarchive52 (`POST /api/templates/:id/unarchive`).53- **« Envoyer ce modèle »** : envoi réel par `POST /api/v1/messages/send` avec `template_id` + `variables` (mise en page conservée),54 depuis n'importe quelle identité (boîte ou alias), avec suivi par destinataire ; le panneau d'API donne le cURL du modèle55 (`$SPMAIL_API_KEY`, jamais de jeton). Les variables (description, exemple, obligatoire) s'éditent dans le studio.56- **Identité de marque** : `prefs.templateBrand` (`PUT /api/prefs`, envoyé avec toutes les autres préférences).57- **« Utiliser dans un message »** : la rédaction n'accepte qu'une mise en forme simple (`COMPOSE_ALLOWED_TAGS` : ni `<style>`, ni `<img>`,58 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.59- **Garde de navigation** : `setNavigationGuard` (`state/session.ts`) retient liens internes et bouton Précédent tant que des60 modifications ne sont pas enregistrées ou qu'une génération est en cours.6162```sh63createdb sp_mail_tpldev # une fois64pnpm build && npx playwright test -c tests/e2e/studio/playwright.config.ts65E2E_AI=1 npx playwright test -c tests/e2e/studio/playwright.config.ts -g "IA réelle" # un seul essai réel (payant)66```6768Pile jetable distincte de celle du webmail : backend sur **8791**, base `sp_mail_tpldev`, aucune boîte ni courrier. La génération est69rejouée depuis `tests/e2e/fixtures/generate-welcome.sse` (flux réel enregistré) par un petit serveur local vers lequel70`page.route` détourne la requête. Sorties dans `/tmp/spmail-e2e-studio`.7172## Toutes les boîtes, identités d'envoi, console d'administration7374- **Boîte unifiée (`/u/<vue>`)** : `state/unified.ts` + `ui/Unified.tsx`, bâtis sur `GET /api/v1/messages` (session, curseur composite75 opaque ; logique pure dans `mail/unified.ts`). Vues : réception, non lus, favoris, brouillons, envoyés, programmés76 (`/api/v1/messages/scheduled`, annulables). Sous-ensemble de boîtes : `prefs.unifiedMailboxes`, enregistré par `PATCH /api/prefs`77 (fusion). Un message s'ouvre dans le lecteur habituel : sa boîte devient la boîte courante (`enterMailbox`), les actions du78 lecteur restent du JMAP. L'identifiant JMAP est lu dans l'identifiant `/api/v1` (`decodeV1Id`, format de `server/src/v1/ids.ts`).79 Rafraîchissement : états `Email` des boîtes retenues (EventSource existants). Raccourci `g a`.80- **Identités d'envoi** : `mail/identities.ts` + `state/senders.ts` — boîtes et alias (`GET /api/v1/addresses`, actifs et autorisés81 à envoyer), groupés par boîte. Une boîte envoie par JMAP (comme avant) ; un **alias envoie par `POST /api/v1/messages/send`**82 (le serveur vérifie l'adresse et construit `From` ; pièces jointes remises par `POST /api/v1/files` ; suivi par83 `GET /messages/outbound/{id}`). Changer d'identité remplace le bloc `.spm-signature` sans toucher au texte tapé.84- **Console (`/admin/<section>`)** : `ui/admin/Admin.tsx` (navigation groupée) ; briques communes dans `ui/admin/kit.tsx` —85 `sensitive()` (invite de clé d'accès sur `403 reauth_required`, puis nouvel essai unique), `SecretDialog` (secret montré une86 fois, jamais conservé), `SafeHtmlFrame` (HTML non fiable dans un cadre isolé), `AddressPicker`.8788```sh89createdb sp_mail_admindev # une fois90pnpm build && npx playwright test -c tests/e2e/admin/playwright.config.ts91```9293Pile jetable : backend sur **8811** (travailleurs actifs, crochet d'essai `SPMAIL_TREAT_AS_EXTERNAL`), base `sp_mail_admindev`, vrai94Stalwart ; boîtes et alias `web-*@stg.spboucher.ai` créés puis purgés (contrôle par `/api/admin/overview`). Sorties dans95`/tmp/spmail-e2e-admin`.9697## Choix à connaître9899- **HTML des messages** : DOMPurify + seconde passe (`mail/sanitize.ts`), rendu dans `<iframe sandbox>` sans `allow-scripts` ni100 `allow-same-origin`, CSP interne `default-src 'none'; img-src data:`. Les images autorisées sont récupérées par la page (mandataire101 `/api/img`, ou passerelle pour `cid:`) et injectées en `data:`. La hauteur du cadre vient d'un gabarit invisible mesuré hors du cadre.102- **Mot-clé `$pinned`** (propre à SP Mail) : message épinglé, trié en tête de son dossier. `$junk` / `$notjunk` accompagnent le signalement.103- **Règles et réponse automatique** : un seul script Sieve « spmail » (voir `mail/sieve.ts`) — sur Stalwart, `VacationResponse/set`104 désactiverait le script de règles.105- **Téléversement** : toujours `application/octet-stream` (le vrai type voyage dans `Email/set`).106