Skip to content
AMN Docs

Roadmap — Intégration Better Auth Cloudflare pour Starlight

Switch to normal modeSwitch to Presentation Mode

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

Section titled “1. Contexte et Objectifs”

1.1. Situation Actuelle

Section titled “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

Section titled “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

Section titled “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)

Section titled “2. Phase 1 : Documentation et Recherche (DOC)”

2.1. Recherche Documentation Officielle

Section titled “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

Section titled “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

Section titled “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)

Section titled “3. Phase 2 : Spécification (SPEC)”

3.1. Spécification Better Auth Cloudflare

Section titled “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é

Section titled “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é

Section titled “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 Configuration

Section titled “3.4. Spécification Configuration”
  • 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

Livrables :

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

4. Phase 3 : Implémentation (CODE)

Section titled “4. Phase 3 : Implémentation (CODE)”

4.1. Infrastructure Cloudflare

Section titled “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

Section titled “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

Section titled “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

Section titled “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é

Section titled “4.5. Sécurité”
  • 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)

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)

Section titled “5. Phase 4 : Tests (TEST)”

5.1. Tests Unitaires

Section titled “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

Section titled “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

Section titled “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é

Section titled “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 Locale

Section titled “5.5. Validation Locale”
  • 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)

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)

Section titled “6. Phase 5 : Intégration et Documentation (INTÉG)”

6.1. Documentation Utilisateur

Section titled “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

Section titled “6.2. Documentation Technique”
  • Mettre à jour ADR
  • Documenter architecture finale
  • Créer diagrammes d’architecture
  • Documenter configuration wrangler.toml

6.3. Déploiement Dev

Section titled “6.3. Déploiement Dev”
  • Déployer sur Cloudflare dev
  • Valider déploiement
  • Tester en environnement dev
  • Documenter résultats

6.4. Préparation Prod

Section titled “6.4. Préparation Prod”
  • Préparer configuration prod
  • Documenter différences dev/prod
  • Créer checklist déploiement prod
  • Préparer rollback plan

Livrables :

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

7. Ordre d’Exécution Recommandé

Section titled “7. Ordre d’Exécution Recommandé”

Priorité 1 (Critique)

Section titled “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)

Section titled “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)

Section titled “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

Section titled “8. Risques et Mitigations”

8.1. Risques Techniques

Section titled “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é

Section titled “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

Section titled “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

Section titled “9. Checklist de Validation”

9.1. Validation Technique

Section titled “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

Section titled “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é

Section titled “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

Section titled “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

Section titled “10. Ressources et Références”

10.1. Documentation Officielle

Section titled “10.1. Documentation Officielle”

10.2. Documentation Projet

Section titled “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

Section titled “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

Section titled “11. Suivi et Reporting”

11.1. Fréquence de Mise à Jour

Section titled “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

Section titled “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

Section titled “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

Section titled “12. Historique des Modifications”
Date Version Description Auteur
2026-09-27 1.0 Création initiale roadmap authentication Starlight Devin

13. Notes Importantes

Section titled “13. Notes Importantes”

13.1. Règles à Respecter

Section titled “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

Section titled “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 Support

Section titled “13.3. Contact et Support”
  • 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

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

Built with StarlightPowered by Cloudflare