Skip to content
AMN Docs

ADR: Intégration de Starlight pour la documentation avec contrôle d'accès Public/Privé

ADR: Intégration de Starlight pour la documentation avec contrôle d'accès Public/Privé

Documentation technique

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

1. Contexte et Problématique1/2

Dans le cadre du projet, la documentation technique (~/PP/docs) et les guides de prise en main (~/PP/GettingStarted) doivent être publiés et consultables via le site de documentation Astro Starlight.

Cependant, l’ensemble de ces documents ne doit pas être accessible publiquement :

  1. Documents Publics : Pages de présentation générale, aperçu du projet et guides d’accueil non sensibles.
  2. Documents Privés : Spécifications techniques (DAT, ADR, SOP, GettingStarted internes, variables et secrets), réservés uniquement aux utilisateurs authentifiés.

1. Contexte et Problématique2/2

L’objectif est d’intégrer Starlight dans la couche de présentation (L2) tout en imposant un contrôle d’accès strict (SSR & Middleware) en synergie avec un Worker d’authentification dédié dans la couche Backend (L3).

2. Décision Architecturale1/3

Nous décidons d’adopter l’architecture suivante :

  1. Montage des répertoires de contenu (L1/L2) :

    • Configurer Starlight et la couche de contenu Astro (src/content.config.ts) avec des chargeurs glob() ciblant les répertoires ../../docs et ../../GettingStarted.
    • Étendre le schéma Frontmatter Starlight avec une propriété visibility: 'public' | 'private' (valeur par défaut : 'private').

2. Décision Architecturale2/3

  1. Rendu dynamique et Protection SSR (L2) :

    • Désactiver le pré-rendu statique (prerender = false) sur les routes de documentation privées pour éviter toute fuite de contenu HTML statique sur le CDN.
    • Utiliser Astro SSR Middleware (apps/web/src/middleware.ts) pour intercepter chaque requête sur la documentation.

2. Décision Architecturale3/3

  1. Délégation d’Authentification vers L3 (Service Binding) :

    • Pour chaque requête ciblant un document privé, le Middleware Astro interroge le Worker L3 auth-handler via Cloudflare Service Binding (env.AUTH_HANDLER) en production et via HTTP local en développement.
    • Si la session est invalide ou manquante, l’utilisateur est réécrit ou redirigé vers la page de connexion /login?redirectTo=....

3. Justification du choix

3.1. Pourquoi Starlight + Astro Middleware ?

  • Transparence et intégration native : Starlight s’appuie sur le système de routage et de middleware natif d’Astro, permettant de sécuriser n’importe quelle route sans modifier le moteur de rendu de Starlight.
  • Sécurité SSR renforcée : En mode SSR à la demande, les documents marqués private ne sont jamais générés sous forme de fichiers HTML statiques accessibles en clair sur le serveur de fichiers statiques.

3.2. Pourquoi déléguer la vérification au Worker L3 (auth-handler) ?

  • Découplage des responsabilités : La couche Présentation (L2) n’a pas à gérer les secrets d’authentification, le hachage des mots de passe ou les sessions KV. Elle délègue cette logique métier à la couche Backend (L3).
  • Performance : Les appels entre le middleware d’Astro (apps/web) et le Worker auth-handler utilisent les Service Bindings Cloudflare, garantissant des temps de réponse sous la milliseconde sans surcoût réseau.

4. Conséquences de la décision

Effets Positifs (Avantages)

  • Sécurité et étanchéité : Impossible d’accéder aux contenus privés sans cookie/session valide contrôlé par le Worker L3.
  • Flexibilité éditoriale : Possibilité de basculer un document de private à public directement dans son frontmatter YAML.
  • Continuité Docs-as-Code : Les répertoires docs/ et GettingStarted/ restent les sources de vérité uniques dans le dépôt Git.

Effets Négatifs (Inconvénients & Risques)

  • Rendu à la demande (SSR) : Les pages privées nécessitent un rendu serveur dynamique, ce qui impose une exécution Cloudflare Worker à chaque visite (latence minimale grâce aux Workers).
  • Indexation Pagefind : Les documents privés doivent être exclus de l’indexation publique Pagefind ou marqués d’un attribut de données filtré pour les utilisateurs non connectés.

5. Alternatives Exclues

  1. Protéger les documents uniquement côté client (JS) : Exclus car le HTML serait lisible dans le code source de la page ou via les fichiers statiques.
  2. Dupliquer les documents dans src/content/docs : Exclus pour respecter le principe de source unique et ne pas fragiliser la maintenance.
  3. Tout mettre en public : Exclus car le projet comporte des spécifications et des guides d’architecture internes sensibles.

6. Historique des modifications

Date Version Description Auteur
2026-09-24 1.0 Création initiale de l’ADR Starlight Auth Team (Agent)
Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare