SPB Git

Repository Public

README.md 8.2 KB

# 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) et ui/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

sh
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/web

# Tests de bout en bout

sh
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 interne default-src 'none'; img-src data:) et n'est affiché que dans un <iframe sandbox> sans allow-scripts ni allow-same-origin (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:.
  • Rendu clair / sombre : aucun script dans le cadre, donc templates/darkmode.ts réécrit les @media (prefers-color-scheme: …) (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.
  • Génération : POST /api/templates/generate lu par fetch + ReadableStream (templates/sse.ts), annulable (AbortController) ; l'état vit dans state/templates.ts (T.generation). Temps écoulé et caractères reçus seulement : aucun pourcentage inventé.
  • Suppression annulable : la requête DELETE archive 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/send avec template_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.
sh
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 sur GET /api/v1/messages (session, curseur composite opaque ; logique pure dans mail/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é par PATCH /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 de server/src/v1/ids.ts). Rafraîchissement : états Email des boîtes retenues (EventSource existants). Raccourci g 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 par POST /api/v1/messages/send (le serveur vérifie l'adresse et construit From ; pièces jointes remises par POST /api/v1/files ; suivi par GET /messages/outbound/{id}). Changer d'identité remplace le bloc .spm-signature sans toucher au texte tapé.
  • Console (/admin/<section>) : ui/admin/Admin.tsx (navigation groupée) ; briques communes dans ui/admin/kit.tsx — sensitive() (invite de clé d'accès sur 403 reauth_required, puis nouvel essai unique), SecretDialog (secret montré une fois, jamais conservé), SafeHtmlFrame (HTML non fiable dans un cadre isolé), AddressPicker.
sh
createdb sp_mail_admindev                                            # une fois
pnpm build && npx playwright test -c tests/e2e/admin/playwright.config.ts

Pile 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> sans allow-scripts ni allow-same-origin, CSP interne default-src 'none'; img-src data:. Les images autorisées sont récupérées par la page (mandataire /api/img, ou passerelle pour cid:) et injectées en data:. 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 / $notjunk accompagnent le signalement.
  • Règles et réponse automatique : un seul script Sieve « spmail » (voir mail/sieve.ts) — sur Stalwart, VacationResponse/set désactiverait le script de règles.
  • Téléversement : toujours application/octet-stream (le vrai type voyage dans Email/set).
Files main
Menu

Theme