ADR: Service Worker Cloudflare `auth-handler` pour la gestion de l'authentification et des sessions

• Statut : Proposé
• Date : 2026-09-24
• Auteur : Team (Agent)

---

1. Contexte et Problématique

Pour restreindre l’accès aux documents privés de la documentation (ADR, DAT, GettingStarted internes) ainsi qu’à d’autres ressources protégées du site, nous devons disposer d’un service d’authentification autonome et sécurisé dans la couche Backend (L3).

Ce service doit :

1. Authentifier les utilisateurs (login/password ou jeton sécurisé).
2. Émettre et vérifier des cookies de session sécurisés (auth_session).
3. Fournir une API ultra-rapide de vérification de session pour le middleware de la couche Présentation (apps/web).
4. S’intégrer parfaitement dans l’architecture Cloudflare Workers (services/auth-handler).

---

2. Décision Architecturale

Nous décidons de créer un nouveau Worker Cloudflare dans la couche L3 : services/auth-handler (amn-auth-handler).

L’architecture retenue est la suivante :

1. Endpoints exposés :

   • POST /api/auth/login : Vérification des identifiants et création d’une session.
   • POST /api/auth/logout : Révocation de la session et suppression du cookie.
   • GET /api/auth/verify : Vérification rapide d’un jeton/cookie de session transmis par le middleware L2.

2. Stockage et Gestion de Session :

   • Stockage des sessions actives dans un espace de nom Cloudflare Workers KV (AUTH_SESSIONS_KV).
   • Signature des jetons de session via HMAC-SHA256 avec un secret AUTH_SECRET (injecté via .env / Cloudflare Secrets).
   • Positionnement de cookies HttpOnly; Secure; SameSite=Lax.

3. Liaison L2 ↔ L3 (Service Binding) :

   • En production, apps/web communique avec amn-auth-handler via la liaison Service Binding AUTH_HANDLER.
   • En développement local, communication via fallback HTTP direct sur http://localhost:8790.

---

3. Justification du choix

3.1. Pourquoi un Worker dédié dans services/auth-handler ?

• Isolation architecturale L3 : Conforme aux règles du projet. La logique d’authentification et le secret ne résident pas dans le front-end Astro mais dans un microservice dédié.
• Réutilisabilité : Le Worker auth-handler pourra ultérieurement sécuriser d’autres services (ex: tableaux de bord admin, soumissions de formulaires réservées).

3.2. Pourquoi Cloudflare KV + HTTP-Only Cookies ?

• Sécurité maximale contre XSS : Les jetons dans un cookie HttpOnly ne sont pas lisibles par du code JavaScript s’exécutant dans le navigateur.
• Révocation instantanée : Grâce à Workers KV, une session peut être invalidée immédiatement lors du logout sans attendre l’expiration du jeton.

---

4. Conséquences de la décision

Effets Positifs (Avantages)

• Latence ultra-faible : La vérification de session via Service Binding s’exécute directement en mémoire sur le réseau Cloudflare sans passer par Internet.
• Conformité aux règles du projet : Respect strict du modèle 3 couches (L1, L2, L3).

Effets Négatifs (Inconvénients & Risques)

• Gestion du dual-mode : Code d’intégration dans apps/web gérant à la fois les appels HTTP locaux (dev) et les Service Bindings (prod).
• Configuration Wrangler : Ajout d’une liaison AUTH_HANDLER et AUTH_SESSIONS_KV dans wrangler.toml.

---

5. Alternatives Exclues

1. Service tiers SaaS (Auth0, Clerk, Firebase Auth) : Exclu pour cette étape afin d’éviter la dépendance à un service externe payant/lourd et conserver la souveraineté complète sur l’infrastructure Cloudflare.
2. Authentification intégrée directement dans Astro : Exclue car la logique métier et le stockage d’auth doivent résider dans la couche L3.

---

6. Historique des modifications

Date	Version	Description	Auteur
2026-09-24	1.0	Création initiale de l’ADR Auth Worker	Team (Agent)