Skip to content
AMN Docs

Analyse du Système d'Authentification Starlight - État des Lieux (CORRIGÉ)

Analyse du Système d'Authentification Starlight - État des Lieux (CORRIGÉ)

Documentation technique

Basé sur mon analyse approfondie du projet, voici le rapport complet sur le système d’authentification aux documents privés du site Starlight :

1. État des Lieux1/2

Architecture actuelle :

  • Middleware Astro (<ref_file file=“/home/anderson/PP/apps/web/src/middleware.ts” />) : Intercepte toutes les requêtes vers /docs/* et /gettingStarted/* (CORRIGÉ)
  • Worker Auth-Handler (<ref_file file=“/home/anderson/PP/services/auth-handler/src/index.ts” />) : Microservice L3 gérant l’authentification
  • Service Binding (<ref_file file=“/home/anderson/PP/apps/web/wrangler.toml” />) : Lien entre l’app web et auth-handler via AUTH_HANDLER
  • Configuration Starlight (<ref_file file=“/home/anderson/PP/apps/web/astro.config.mjs” />) : Utilise docsLoader() avec copie de fichiers via scripts predev/prebuild (CORRIGÉ)

1. État des Lieux2/2

Stack technique :

  • Astro SSR avec adapter Cloudflare
  • Cloudflare Workers + Service Bindings
  • Cloudflare D1 + KV pour stockage des données
  • Better Auth Cloudflare (à intégrer) pour l’authentification
  • Middleware Astro pour contrôle d’accès

2. Documents Privés vs Publics1/2

État actuel :

  • TOUS les documents sont considérés PRIVÉS par défaut (ligne 32 du middleware : let isPrivate = true)
  • Seule exception : Le document overview est explicitement public (lignes 48-50)
  • Schéma de visibilité : Le champ visibility doit être implémenté pour permettre des documents publics spécifiques
  • Aucun document n’a actuellement de champ visibility dans son frontmatter
  • Stratégie requise : Tous les docs privés par défaut, avec possibilité d’activation publique facile

2. Documents Privés vs Publics2/2

Structure des documents :

  • /docs/* : Documentation technique (L1, L2, L3, PM, SOP) - TOUS PRIVÉS PAR DÉFAUT
  • /gettingStarted/* : Guides de prise en main - TOUS PRIVÉS PAR DÉFAUT
  • /overview : Page d’accueil docs - PUBLIC
  • Gestion des fichiers : Copie via scripts predev/prebuild (<ref_file file=“/home/anderson/PP/apps/web/package.json” lines=“9,11” />) depuis ../../docs et ../../GettingStarted

3. Mécanisme d’Authentification1/2

Flux actuel :

Utilisateur → Requête /docs/xxx
           ↓
    [Middleware Astro]
           ↓
    Document public ? → Non (sauf overview)
           ↓
    Cookie auth_session présent ?
           ↓
    Oui → Vérification via auth-handler
           ↓
    Valide → Accès autorisé
    Invalide → Redirection /login

3. Mécanisme d’Authentification2/2

Implémentation :

  • Développement local : HTTP fetch vers http://127.0.0.1:8790/api/auth/verify
  • Production : Service Binding env.AUTH_HANDLER (Cloudflare Workers) - NON CONFIGURÉ (env=dev uniquement)
  • Cookie : auth_session avec configuration HttpOnly; SameSite=Lax
  • Session : Stockée dans KV avec TTL 24h
  • Stack auth : Better Auth Cloudflare à intégrer (remplacement du système actuel)

4. Login vs Sign Up1/2

État actuel :

  • Seul LOGIN implémenté : Page <ref_file file=“/home/anderson/PP/apps/web/src/pages/login.astro” />
  • PAS de SIGN UP : Aucun mécanisme d’inscription
  • Authentification hardcodée : Credentials administrateur configurés via variables d’environnement :
    • DEFAULT_ADMIN_EMAIL (défaut: admin@example.com)
    • DEFAULT_ADMIN_PASSWORD (défaut: password123)
  • Single user : Un seul utilisateur admin avec rôle ‘admin’

4. Login vs Sign Up2/2

Endpoints auth-handler :

  • POST /api/auth/login : Authentification
  • POST /api/auth/logout : Déconnexion
  • GET /api/auth/verify : Vérification de session
  • GET /health : Health check

5. Actions à Faire1/2

Immédiat (Urgent) :

  1. Corriger les chemins du middleware : ✅ CORRIGÉ - /getting-started/ → /gettingStarted/
  2. Clarifier la gestion des fichiers : Les symlinks ne fonctionnent pas, utiliser les scripts predev/prebuild actuels
  3. Intégrer Better Auth Cloudflare : Remplacer le système auth-handler actuel par better-auth-cloudflare
  4. Configurer D1 + KV : Pour Better Auth (users, sessions, accounts)

5. Actions à Faire2/2

Court terme : 5. Implémenter le schéma de visibilité : visibility: 'public' | 'private' dans le frontmatter Starlight 6. Configurer le middleware : Pour lire et respecter le champ visibility de chaque document 7. Mettre à jour la config Starlight : Sidebar avec les bons répertoires (docs et gettingStarted) 8. Sécuriser les credentials : Remplacer les valeurs par défaut par des secrets via .env

Moyen terme : 9. Configurer l’environnement prod : Quand les données prod seront disponibles 10. Implémenter sign up : Avec Better Auth pour gérer l’inscription multi-users 11. Gérer les rôles et permissions : Via Better Auth pour différents niveaux d’accès

6. Recommandations1/7

Sécurité :

  • ✅ Architecture solide : Service Binding Cloudflare est la bonne approche
  • ⚠️ Authentification actuelle obsolète : Le système auth-handler custom doit être remplacé par Better Auth Cloudflare
  • ⚠️ Credentials vulnérables : Remplacer les valeurs par défaut par des secrets via .env
  • ⚠️ Cookie non sécurisé : Ajouter flag Secure en production
  • ✅ Middleware corrigé : Chemins /gettingStarted/ maintenant corrects

6. Recommandations2/7

Architecture :

  • ✅ Bonne séparation des responsabilités : L2 (Présentation) vs L3 (Backend)
  • ✅ Service Binding approprié : Communication Workers optimisée
  • ⚠️ Gestion des fichiers : Scripts predev/prebuild fonctionnels mais symlinks inutilisés
  • ⚠️ Schéma de visibilité à implémenter : Nécessaire pour gérer public vs privé

6. Recommandations3/7

Stack technique :

  • ✅ Astro SSR + Cloudflare : Bon choix pour l’architecture
  • ✅ Better Auth Cloudflare : Solution moderne et adaptée à Cloudflare Workers
  • ✅ D1 + KV : Stack appropriée pour Better Auth
  • ⚠️ Env=dev uniquement : Configuration prod non encore disponible

6. Recommandations4/7

Expérience utilisateur :

  • ⚠️ Pas d’inscription : Actuellement limité à un seul admin
  • ⚠️ UX basique : Page de login fonctionnelle mais minimaliste
  • ✅ Redirection fonctionnelle : redirectTo bien géré
  • ⚠️ Visibilité non configurable : Impossible de marquer des docs comme publics

6. Recommandations5/7

Conformité documentation officielle :

  • ✅ Service Binding : Conforme aux best practices Cloudflare
  • ✅ Middleware Astro : Utilisation correcte de defineMiddleware
  • ✅ Better Auth : Solution recommandée par documentation Astro pour Cloudflare
  • ⚠️ Gestion fichiers : Scripts de copie fonctionnels mais optimisation possible

6. Recommandations6/7

Prochaines étapes recommandées :

  1. Intégrer Better Auth Cloudflare en remplacement du système auth-handler actuel
  2. Implémenter le schéma de visibilité visibility: 'public' | 'private' dans Starlight
  3. Configurer D1 + KV pour Better Auth (users, sessions, accounts)
  4. Mettre à jour le middleware pour lire et respecter le champ visibility
  5. Sécuriser les credentials via variables d’environnement
  6. Tester le flux complet avec Better Auth en environnement dev
  7. Préparer la configuration pour l’environnement prod quand disponible

6. Recommandations7/7

Le système nécessite une refonte de l’authentification vers Better Auth Cloudflare et l’implémentation du système de visibilité pour être conforme aux requirements.

Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare