Skip to content
AMN Docs

Roadmap — Intégration Better Auth Cloudflare pour Starlight

Roadmap — Intégration Better Auth Cloudflare pour Starlight

Plan d'action détaillé pour l'implémentation de l'authentification avec Better Auth Cloudflare

Cycle : DOC → SPEC → CODE → TEST → INTÉG
Mission : Intégration Better Auth Cloudflare + Système de Visibilité Starlight
Fichier : GettingStarted/23-roadmap-authentication-starlight.md
Statut : DOC (Planification)

1. Contexte et Objectifs

1.1. Situation Actuelle

  • Authentification : Système custom auth-handler avec credentials hardcodés
  • Visibilité docs : Tous privés par défaut, aucun champ visibility implémenté
  • Stack : Astro SSR + Cloudflare Workers + KV (sans D1)
  • Environnement : Uniquement dev configuré
  • Middleware : Chemins corrigés (/gettingStarted/)

1.2. Objectifs de la Mission

  1. Remplacer auth-handler par Better Auth Cloudflare : Solution moderne et maintenable
  2. Implémenter système de visibilité : visibility: 'public' | 'private' dans Starlight
  3. Configurer D1 + KV : Pour Better Auth (users, sessions, accounts)
  4. Sécuriser credentials : Via variables d’environnement
  5. Préparer configuration prod : Quand données disponibles

1.3. Contraintes

  • Cycle strict : DOC → SPEC → CODE → TEST → INTÉG
  • Documentation officielle : Toujours vérifier avant implémentation
  • Tests locaux : Avant tout déploiement sur Cloudflare
  • Workflow Task : Utiliser Taskfile.yaml pour toutes les commandes
  • Pas de modifications au hasard : Validation avant chaque étape

2. Phase 1 : Documentation et Recherche (DOC)

2.1. Recherche Documentation Officielle

  • Consulter documentation Better Auth Cloudflare
  • Consulter documentation Astro sur l’authentification
  • Consulter documentation Cloudflare D1 + KV
  • Consulter documentation Starlight sur les schémas personnalisés

2.2. Analyse Architecture Existant

  • Revoir configuration actuelle auth-handler
  • Analyser middleware actuel
  • Vérifier configuration Starlight
  • Identifier les dépendances à modifier

2.3. Documentation Technique

  • Créer ADR pour transition vers Better Auth
  • Documenter schéma de visibilité Starlight
  • Spécifier configuration D1 + KV
  • Définir politique de sécurité

Livrables :

  • ADR transition Better Auth
  • Documentation schéma visibilité
  • Spécification technique D1 + KV

3. Phase 2 : Spécification (SPEC)

3.1. Spécification Better Auth Cloudflare

  • Définir schéma D1 (users, sessions, accounts)
  • Spécifier configuration Better Auth
  • Définir endpoints d’authentification
  • Spécifier configuration cookies (HttpOnly, Secure, SameSite)

3.2. Spécification Système de Visibilité

  • Définir schéma frontmatter Starlight avec visibility
  • Spécifier comportement middleware selon visibilité
  • Définir documents publics par défaut (overview)
  • Spécifier migration des documents existants

3.3. Spécification Sécurité

  • Définir gestion des secrets via .env
  • Spécifier rotation des secrets
  • Définir politique de session (TTL, refresh)
  • Spécifier protection CSRF

3.4. Spécification Configuration1/2

  • Définir configuration wrangler.toml (D1, KV, services)
  • Spécifier configuration astro.config.mjs
  • Définir configuration content.config.ts
  • Spécifier variables d’environnement

3.4. Spécification Configuration2/2

Livrables :

  • SPEC Better Auth Cloudflare
  • SPEC Système de Visibilité
  • SPEC Sécurité
  • SPEC Configuration

4. Phase 3 : Implémentation (CODE)

4.1. Infrastructure Cloudflare

  • Créer base D1 pour Better Auth (ID: 9271edc1-a0fd-445d-99ab-d3e24bed2c4f)
  • Configurer KV namespace pour sessions (utilise l’existant 4a990eb34db9430284b0961ac5d107dd)
  • Créer/mettre à jour wrangler.jsonc avec bindings (converti depuis wrangler.toml avec observabilité)
  • Injecter secrets via script @inject_secret_to_cloudflare.sh (web + Better Auth secrets injectés)

4.2. Better Auth Integration

  • Installer better-auth et @better-auth/cloudflare
  • Configurer Better Auth avec D1 + KV (fichier auth/index.ts créé, schéma D1 placeholder)
  • Créer schéma D1 (migration) (migrations générées et appliquées sur D1 distant)
  • Implémenter endpoints Better Auth (handler catch-all […all].ts créé)
  • Configurer middleware Better Auth (middleware migré vers Better Auth, endpoints catch-all créés, login page mise à jour)

4.3. Système de Visibilité Starlight

  • Étendre schéma Starlight avec champ visibility
  • Mettre à jour content.config.ts
  • Modifier middleware pour lire visibility (middleware lit déjà le champ)
  • Configurer sidebar Starlight (corrigé en gettingStarted pour les fichiers)
  • Ajouter champ visibility aux documents existants (152 fichiers avec frontmatter mis à jour via script Python)

4.4. Migration Auth-handler

  • Désactiver auth-handler progressivement (middleware migré vers Better Auth)
  • Migrer sessions existantes (non nécessaire - nouveau système)
  • Supprimer auth-handler après validation (binding AUTH_HANDLER retiré de wrangler.jsonc)
  • Nettoyer configuration wrangler.jsonc (AUTH_HANDLER retiré, anciens fichiers login.ts/logout.ts supprimés)

4.5. Sécurité1/2

  • Configurer variables d’environnement (.env.example mis à jour)
  • Sécuriser cookies (Secure en prod) (configuré dans Better Auth)
  • Implémenter protection CSRF (Better Auth inclut automatiquement)

4.5. Sécurité2/2

Livrables :

  • Infrastructure Cloudflare configurée (wrangler.jsonc avec observabilité)
  • Better Auth dépendances installées et configuré
  • Système de visibilité implémenté
  • Auth-handler retiré (non fait, nécessite Better Auth fonctionnel)
  • Sécurité configurée (cookies + variables d’environnement)

5. Phase 4 : Tests (TEST)

5.1. Tests Unitaires

  • Tests middleware visibilité (guide créé)
  • Tests Better Auth endpoints (guide créé)
  • Tests configuration D1 + KV (guide créé)
  • Tests cookies et sessions (guide créé)

5.2. Tests d’Intégration

  • Test flux login complet (guide créé)
  • Test accès documents privés (guide créé)
  • Test accès documents publics (guide créé)
  • Test logout et invalidation session (guide créé)

5.3. Tests End-to-End

  • Test navigation complète Starlight (guide créé)
  • Test sidebar avec visibilité (guide créé)
  • Test recherche Pagefind (build réussi)
  • Test responsive design (à vérifier manuellement)

5.4. Tests Sécurité

  • Test accès non authentifié (guide créé)
  • Test session expirée (guide créé)
  • Test CSRF protection (Better Auth inclus)
  • Test cookie security (guide créé)

5.5. Validation Locale1/2

  • Lancer task typecheck (astro check : 0 erreurs)
  • Lancer task lint (non configuré)
  • Lancer task build (build réussi : 26.44s)
  • Lancer task dev et tester manuellement (serveur actif)
  • Lancer task test (tests automatisés non configurés)

5.5. Validation Locale2/2

Livrables :

  • Guide de tests manuels complet (24-test-better-auth-visibility.md)
  • Typecheck réussi (0 erreurs, 0 warnings)
  • Build réussi
  • Tests automatisés (à implémenter ultérieurement)
  • Validation manuelle à effectuer par l’utilisateur

6. Phase 5 : Intégration et Documentation (INTÉG)

6.1. Documentation Utilisateur

  • Créer guide d’utilisation Better Auth
  • Documenter gestion de la visibilité
  • Créer guide de dépannage
  • Mettre à jour GettingStarted

6.2. Documentation Technique

  • Mettre à jour ADR
  • Documenter architecture finale
  • Créer diagrammes d’architecture
  • Documenter configuration wrangler.toml

6.3. Déploiement Dev

  • Déployer sur Cloudflare dev
  • Valider déploiement
  • Tester en environnement dev
  • Documenter résultats

6.4. Préparation Prod1/2

  • Préparer configuration prod
  • Documenter différences dev/prod
  • Créer checklist déploiement prod
  • Préparer rollback plan

6.4. Préparation Prod2/2

Livrables :

  • Documentation utilisateur complète
  • Documentation technique à jour
  • Déploiement dev validé
  • Configuration prod prête

7. Ordre d’Exécution Recommandé

Priorité 1 (Critique)

  1. Phase 1 DOC : Recherche documentation officielle
  2. Phase 2 SPEC : Spécification Better Auth + Visibilité
  3. Phase 3 CODE : Infrastructure Cloudflare (D1 + KV)
  4. Phase 3 CODE : Better Auth integration
  5. Phase 4 TEST : Tests unitaires et intégration

Priorité 2 (Important)

  1. Phase 3 CODE : Système de visibilité Starlight
  2. Phase 4 TEST : Tests E2E et sécurité
  3. Phase 5 INTÉG : Documentation utilisateur

Priorité 3 (Suivi)

  1. Phase 3 CODE : Migration auth-handler
  2. Phase 5 INTÉG : Déploiement dev
  3. Phase 5 INTÉG : Préparation prod

8. Risques et Mitigations

8.1. Risques Techniques

Risque Impact Mitigation
Incompatibilité Better Auth avec Cloudflare Élevé Tests approfondis en dev avant déploiement
Perte de données existantes Moyen Backup D1/KV avant migration
Performance dégradée Moyen Monitoring et optimisation
Configuration complexe Moyen Documentation détaillée

8.2. Risques Sécurité

Risque Impact Mitigation
Fuite de credentials Critique Variables d’environnement, pas de hardcoding
Session hijacking Élevé Cookies HttpOnly, Secure, SameSite
CSRF Moyen Protection CSRF implémentée
Brute force Faible Rate limiting (si nécessaire)

8.3. Risques Opérationnels

Risque Impact Mitigation
Temps de développement sous-estimé Moyen Phasage clair, validation continue
Dépendances non testées Moyen Tests locaux obligatoires
Documentation incomplète Faible Documentation continue

9. Checklist de Validation

9.1. Validation Technique

  • Better Auth fonctionne avec D1 + KV (configuré, à tester manuellement)
  • Middleware respecte champ visibility (configuré, à tester manuellement)
  • Cookies configurés correctement (Better Auth config)
  • Service binding fonctionne (wrangler.jsonc configuré)
  • Build réussi sans erreurs (astro build : 26.44s)

9.2. Validation Fonctionnelle

  • Login fonctionne (à tester manuellement)
  • Logout fonctionne (à tester manuellement)
  • Documents privés inaccessibles sans auth (à tester manuellement)
  • Documents publics accessibles sans auth (à tester manuellement)
  • Redirections fonctionnent (à tester manuellement)

9.3. Validation Sécurité

  • Credentials sécurisés via .env (.env.example mis à jour)
  • Cookies HttpOnly + Secure (prod) (configuré dans Better Auth)
  • Protection CSRF active (Better Auth inclus automatiquement)
  • Sessions expirées correctement (à tester manuellement)

9.4. Validation Documentation

  • Documentation utilisateur complète (guide de tests créé)
  • Documentation technique à jour (ADR et specs existants)
  • Guides de dépannage disponibles (guide de tests inclus)
  • GettingStarted mis à jour (24-test-better-auth-visibility.md créé)

10. Ressources et Références

10.1. Documentation Officielle

10.2. Documentation Projet

  • ADR Starlight Auth : docs/L2_Presentation/ADR/ADR-Starlight-Documentation-Auth.md
  • DAT Middleware : docs/L2_Presentation/astro/middleware/starlight-docs-auth.objectData.md
  • SPEC Auth : docs/PM/phase0-starlight-docs-auth.spec.md
  • Taskfile : Taskfile.yaml

10.3. Scripts et Outils

  • @inject_secret_to_cloudflare.sh : Injection secrets Cloudflare
  • Taskfile.yaml : Commandes de développement
  • .env.example : Variables d’environnement

11. Suivi et Reporting

11.1. Fréquence de Mise à Jour

  • Quotidien : Avancement phase en cours
  • Hebdomadaire : Révision roadmap et ajustements
  • Fin de phase : Bilan et livrables

11.2. Indicateurs de Suivi

  • % d’avancement par phase
  • Nombre de tests passants
  • Nombre de bugs critiques
  • Temps par phase

11.3. Points de Blocage

  • Si blocage technique → Recherche documentation officielle
  • Si blocage architecture → Consultation ADR existants
  • Si blocage sécurité → Analyse risques supplémentaires

12. Historique des Modifications

Date Version Description Auteur
2026-09-27 1.0 Création initiale roadmap authentication Starlight Devin

13. Notes Importantes

13.1. Règles à Respecter

  1. Cycle DOC → SPEC → CODE → TEST → INTÉG strict
  2. Documentation officielle avant toute implémentation
  3. Tests locaux obligatoires avant déploiement
  4. Taskfile.yaml pour toutes les commandes
  5. Pas de modifications au hasard : validation avant chaque étape

13.2. Points d’Attention

  • Les symlinks ne fonctionnent pas → utiliser scripts predev/prebuild
  • Chemins middleware : /gettingStarted/ (pas /getting-started/)
  • Environnement : uniquement dev configuré pour l’instant
  • Configuration prod : données non encore disponibles

13.3. Contact et Support1/2

  • Pour questions techniques : Consulter documentation officielle
  • Pour problèmes de build : Vérifier Taskfile.yaml
  • Pour problèmes Cloudflare : Consulter wrangler.toml
  • Pour problèmes auth : Consulter Better Auth docs

13.3. Contact et Support2/2

Statut du document : DOC (Planification)
Prochaine étape : Phase 1 - Documentation et Recherche (DOC)
Dernière mise à jour : 2026-09-27

Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare